Vulkan documentation just got easier! The Vulkan Working Group has gathered all the key documents including the specifications, guides, tutorials and samples into a single website to allow developers to navigate quickly to the information they need.
It is unclear from this page what documentation is going to continue to be supported and what is not.
For example, will there still be PDFs? The docs.vulkan website doesn’t seem to have links to any. If there are going to still be PDFs, then there should probably be some links to them.
And if there will still be PDFs, will it just be one PDF (current version + all extensions) or will there be multiple PDFs provided?
Address the needs for the full range of developer experience
I’m not sure how throwing the full complexity of current version+all extensions helps with that. The nice thing about 1.3 or 1.3+KHR is that… it’s shorter. The core information is more readily available and digestible from the specification. And sure, 1.3 does contain a lot of cruft (API functions that still exist but are duplicates of extensible versions of that API, etc), but there are a lot of Vulkan extensions.
The extended version of the specification is just a lot less readable and comprehensible, particularly for relatively new users. Is the expectation that such users shouldn’t read the specification and instead should use the tutorials or the guide?
- The existing 1.3+all extensions spec in the registry will continue
to be published in HTML and PDF form, as will the HTML refpages. - The 11 other variants currently published will be retired and (to
the degree possible) redirected to the 1.3+all extensions spec. - The new docs.vulkan.org HTML site will be published in the same
1.3+all extensions variant.
Will the docs.vulkan site actually link to the PDF? Because at present, I see no links to it. A single PDF has a number of advantages (a search that isn’t an “internet search” that tries to search for what you meant instead of what you asked, for example), so it would be good if it weren’t hidden.
As for essentially “retiring” all other versions of the specification, I don’t know how I should recommend the specification going forward.
I’ve always been a big proponent of pushing newer users to reading the specification itself. The Vulkan specification can be a very readable document, and while it has a bit of complexity to it, the document itself is pretty reasoanble and digestible.
But that is only true of the core-only specification (or core+KHR, as there aren’t that many KHR extensions). Once you start shoving every single extension into the document, it quickly becomes an unreadable mess. If you’re trying to understand how synchronization works, having to jump over a bunch of vendor-specific information inbetween the kernels of information that is relevant to Vulkan as a whole just isn’t helpful. Users learning Vulkan need to learn Vulkan, not a bunch of vendor stuff or edge-case extensions.
Basically, I’m not sure that I can in good conscious recommend to newer Vulkan users that they should read a document that now only contains 40% of the information they actually need to know and 60% of a bunch of unimportant stuff that will just confuse them.
So how should we expect users to use the specification going forward?