Documentation as Code
Documentation as Code (Docs-as-Code) is quite to my heart. Especially as I'm not so good at it, and something I have been struggling for a long time and still am. But it's one of the things that is so important but also disliked so much by a lot of technical people. And the sad thing is, that the technical people are the ones that need to transfer the knowledge. They don't have to write the documentation, but they are the ones who know how things work and why they are built the way they are. So they could have come up with the concept of Documentation as Code (Docs-as-Code) much earlier. But it looks like it's one of these things where first all the pieces have to fall into place before it keeps on getting traction. Especially, as developers like to pride themselves on the fact, that they automate repeating tasks.
But what is Docs-as-Code? Actually, the website that you are looking at currently is built using one concept of Documentation as Code. It is built using Docusaurus. It's a static site generator, that uses Markdown and React. Out of these, it builds a website that can be deployed and hosted by a lot of providers.
There are many advantages of this concept. Some of them I found on the Write the Docs page:
- Using tools and processes that developers are already familiar with
- Keep up with the changes and reduce the amount of outdated documentation
- Automatically extract the information developers put in code
- Let Developers write the first draft
One of the biggest struggles, I came across and faced myself, is how to ensure that the documentation that you write keeps up to date with the changes you make in the code or infrastructure. Who hasn't been bitten by an outdated comment, or piece of documentation?
So what better idea to use code to extract the information with ever change that you make to your code? Luckily there is an increasing amount of tools that help you enhance documentation, by extracting information out of the code or create diagrams based on the information in the code.
If you want to learn more about this concept, you can head over to the page from Anne Gentle: Docs like Code. There you can find a lot of resources to dive deep into the topic of documentation as code.