Documentation as Code

Documentation often poses a challenge for many teams, yet its importance cannot be understated, particularly for those on-call. Effective documentation can expedite the response to outages and minimize downtime.

One approach that I have found to be effective is treating documentation as code and including it within the Git repositories. This practice increases the likelihood of keeping documentation updated as changes are made in the repository.

Having documentation within the repository currently being worked on, rather than tucked away in another tool or hidden subpages, makes it more accessible and convenient to maintain.

Tools like 'mkdocs-material' are particularly useful for generating searchable, well-structured, and visually appealing documentation from Markdown files. For instance, this website is generated entirely from Markdown files.