161 - Getting More Serious About Documentation
Channel: StableCoder
Date: 2022-05-11

The bane of many developer's existence is documentation. Both not having good enough documentation to read for specs or API's from others, and not generating enough for whatever I  develop myself.

Unfortunately, the size and scope of the project has grown to the point that it is actively stretching what I can properly remember, and with time details for how some aspects work are slowly being eroded.

As such, this session focuses on figuring out what to do about that. Some proper documentation is in order, to fulfill several purposes:
- Document the motivations, ideas, and concepts being implemented
- Keep a single location where the broader contexts can be searched, read, and how things fit together are explained
- Generate attractive, readable PDF and web output
- Help stabalize functionality. Changing functionality takes more effort than changing the code, thus more though would hopefully be put into future changes, but not enough to cause stagnation.

The initial idea was to re-use a solution used previously, Doxygen, which can generate some form of documentation extracted from the code itself, mostly through the inlined comments, mostly around functions. This is seemingly attractive, as it should change as the code itself changes, but this would be a double-edged sword, as developers are more willing to make ad-hoc changes with the compensating documentation, sometimes not taking into account how well those changes fit into the overall codebase. Not only that, much documetation and evolved to a disjointed, fragmented environment where the larger context became lost over multiple changes across the codebase. Doxygen's output was also always janky enough to the point where other developers wouldn't make much use of it, and I would often feel the same when encountered on other projects.

The idea quickly shifted towards looking at what the Khronos group does for documentation. Having used their Vulkan and OpenXR standards quite a bit during development, I have grown to admire their documentation, and after looking at what they used, seeing the excellent HTML and PDF output, flexibility, moddability, I decided to establish some documentation based on what they do, using the Ruby-based Asciidoctor.

--

2022/04/27