Revolutionize Your Documentation: Treat it Like Code

Writing documentation is one really crucial part of a job in Software Engineering. Documentation can be written and maintained in several formats through different procedures. Nonetheless, I truly believe treating documentation as code is the way to go, but how can we achieve this and which are the advantages?

Photo by Sigmund on Unsplash

Choose a markup language

The same way we use programming languages and different IDEs for code, we will use certain tools for writing our documentation.

First of all, I am huge believer in using markup languages for documentations. Why? Because it is consistent, portable, reusable and easy to search on it.

For markup languages we have several option such as Markdown, LaTex, reStructuredText, etc. My favourite one is Markdown because nowadays it is simply a standard in the industry of Software Engineering.

Use a Version Control System (VCS)

In order to improve the collaboration and maintain properly code that is shared by several engineers, we need to use a VCS, so for documentation would be the same.

Documentation must be updated as code grows or varies, maintaining our documentation in a VCS like Git would allow us to manage and look at all the previous versions we had for our documentation. Who knows if we need to revisit old documentation or simply reset last changes to documentation?

In addition to this, handling the addition of documentation into our VCS through consistent reviews by other engineers, will improve the quality of the new documentation.

Add your documentation to your Continuous Integration (CI)

Continuous Integration (CI) is a quite important process before delivering or deploying our code for having high quality standards and automated testing, among other benefits.

Specially if your documentation is going to be delivered to customers, having CI is a must for having higher quality standards before delivering.

For adding your documentation into your CI process, there several tasks you can add such as:

• Build your documentation: in case you use a markup language that needs to be compiled, making sure your documentation builds successfully before intregating it, is absolutely vital.
• Add linterns: having linterns for your documentation can help to improve the consistance in the format. Some examples of useful linterns may be Markdown lint or ReStructuredText lint.

Advantages of treating documentation as code

We have seen several procedures that we apply for code and could be applied as well for documentation.

All these procedures add a lot of value for our documentation such as improving consistance in the format, facilitating the collaboration between several people or having higher standards in our documentation before integrating it.

Documentation has one huge similarity with code, both rot. This means we need to maintain properly and clean up our documentation as soon as possible, before it is too late.

In a nutshell, take care of your documentation!