Vulkan Documentation has a new home
With something as complex as the Vulkan API, good documentation is crucial for developer adoption. And while Vulkan had pretty good documentation from the get-go, with esp. the spec getting lots of praise, there was a lot of room for improvement. The spec e.g. has become so large that lower-end devices have problems loading it up in the browser, other interesting documentation is scattered around different places and related documentation (e.g. shading languages) was not directly accessible vie the spec.
To make it short: Esp. developers starting with Vulkan had a hard time finding all relevant documentation, let alone know how those documentations worked together. Navigation the eco system itself has become kind of a challenge.
To make it short: Vulkan documentation has a new home and documentation resources have been unified into a single documentation project using the multi-repository documentation generator Antora.
When defining the initial scope we took a look at different Vulkan documentation related projects and decided to start off with the following resources:
- Vulkan Specification
- This is the latest release of the spec
- Vulkan Guide
- Vulkan Tutorial
- Based on Alexander Overvoorde’s excellent Vulkan Tutorial
- We already did several larger additions to his tutorial in the past few months (e.g. a compute shader), and we plan on improving and updating the tutorial in many places, to keep it up-to-date with the api itself
- Vulkan samples
- The official Vulkan samples already had lots of good documentation including dozens of tutorials for the actual samples. It was a natural fit for this project
- Links to related resources
- An HLSL landing page (we plan on extending this in the future), GLSL spec, social sites, forums, etc.
Having all the documentation in one place also allowed us to add a cross-documentation search. That way you’ll get search result for a given term across all the above mentioned resources. This is esp. useful if you search for an extension. You’ll then get results for that in the spec, in the tutorial, the guide and (if available) also a link to a sample for that extension.
Esp. the “old” API specification suffered from long loading times and huge memory requirements. This was one point of criticism we heard a lot and this improved a lot with the new documentation site. Navigation through the spec is now lighting fast, even on lower-end mobile devices.