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.

So as part of a small group inside Khronos I worked on improving this. And the result is now public at docs.vulkan.org. More details can be found in this Khronos blog post.

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.

Scope

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.

Cross-documentation search

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.

Performance

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.