Pages Menu
Categories Menu

Posted by on Jun 27, 2019 in Information Management, What's new | 0 comments

How-to use static website generators to build technical documentation

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.

tech documentation imageHow 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.

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.

Post a Reply

Your email address will not be published. Required fields are marked *

🚚 📦 We're moving!

[French below]

The content of the CartoBlog was transferred to the Information Management Resource Portal in May 2021:

Please note that the CartoBlog will be decommissioned in early 2022. From now on, we warmly encourage you to consult the tutorials, benchmarking studies and other resources directly onto the new portal.

Thank you!

🚚 📦 On déménage !

Le contenu du CartoBlog a été transféré sur l’IM Resource Portal en mai 2021 :

Veuillez noter que le CartoBlog sera désactivé au début de l’année 2022. Nous vous invitons, dès à présent, à prendre l’habitude de consulter les tutoriels, benchmarkings et autres ressources directement sur le nouveau portail.

Merci !