How-to use static website generators to build technical documentation

This resource was originally published on the CartoBlog in 2019 by CartONG. It was transferred to the IM Resource Portal in May 2021. The CartoBlog will be decommissioned in early 2022.

Technical documentation is an invaluable resource for projects and software systems. Yet, identifying the ideal documentation tool, setting up the appropriate process while keeping technical project documentation up to date, making it accessible and being efficient about it can be a challenge.

What is technical documentation?

In simple terms, technical documentation is any document that explains the use, functionality, creation, or architecture of a system. The key to writing good technical documentation is in the format of the document. Technical documentation isn’t just about capturing information. It’s about presenting it in a way that’s easy for the reader to understand and use.

Why is technical documentation so important?

The presence of documentation helps keeping track of all aspects of a system and improves its quality over time. Its main focus is easy and efficient development, as well as maintenance and knowledge transfer to other developers. Successful documentation will make information easily accessible, helps to avoid duplication of work, simplify the product and to cut support costs.

How we documented code for one of our partners

CartONG’s partner had set up a project for monitoring economic inclusion programs. The monitoring system had been developed using Google Apps Script which helped with data flow integration from KoboToolbox, by pulling the data collected from its API to Google spreadsheets for analysis and data validation before, finally, publishing to the program’s open data platform.

Part of the work conducted by CartONG’s team since late 2018, was to find a tool for this partner that would allow collaborative editing between the project’s developers, putting all the system’s code in version control and making the documentation process truly agile. In the end, CartONG opted to centralize all technical documentation using Sphinx. There were several steps involved before we could identify a tool that would help the documentation of this project to be clear, consistent and easy to read.