Developer documentation: docs-as-code

Ensure better code with clear documentation

Software requires not only manuals for users, but also documentation for developers. Good developer documentation is essential for efficient developer collaboration and ultimately results in better and more consistent code. In some cases, the documentation is part of a complete software development kit that external developers can use to work independently. But clear documentation can also make a big difference on a smaller scale.

Go beyond a 'README.txt' file: Types of software documentation

When drawing up software documentation, it is important to first clearly identify what information is needed for the various tasks within a software development team. In many cases the documentation was not developed at the same time as the software, and needs to be brought up-to-date. This quickly involves large amounts of information that have to be structured and presented according to the user's needs. Fortunately, we don't have to keep reinventing the wheel. Consciously or subconsciously, developers continuously work with software documentation that is available online. We can leverage this by offering the same specific types of technical documentation, with a fixed and recognizable structure, such as:

• API documentation

• data model documentation

• architectural documentation

• reference pages for functions, events, objects, etc. 

• UX design system 

Write and manage ‘docs-as-code’

We like to follow the 'docs-as-code' approach. This means that we write and manage the documentation in the same way and with the same tools as the code. We usually choose to write the documentation in Markdown because software developers are already familiar with this, but this can also be done with DITA or a combination of both. If the files are always placed in the repository of the described code, they are also easily found and maintained. Markdown and DITA can be converted to HTML to publish the content to a portal. We use a 'static site generator' (such as Eleventy or MkDocs) for this. This approach has the advantage that various plugins are immediately available to enrich Markdown with features such as clickable diagrams, code snippets, search and navigation functionalities. This way we ensure that the documentation is appealing as well as user-friendly. When you host your documentation on a platform like Netlify, you can configure it with just a few clicks so that, as a technical writer, you don't have to do anything to publish updates. Changes are automatically published online, either immediately or at the same time as the code is released. This way the user benefits from your documentation very quickly.