How-to use static website generators to build technical documentation
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.
This blog post focuses on a bit of background about technical documentation, before detailing an example of building technical documentation using a static website generator; and outlining the process that CartONG used to select a relevant tool. The full report may be found here.
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.
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.
To learn more about how we selected a relevant tool and set it up for our partner, check out this step-step recap: How to use static website generators to build technical documentation.