Automating documentation using Python

One of the tasks for this week was cleaning up after an infrastructure move and then updating all the documentation. Given that there are many forms of documentation, it was a bit of a task.

I ended up putting together a spreadsheet of the main details so that there is a canonical reference. The first task was to create some diagrams to work out what we had and where, before asking if it matched what I knew. It took several iterations to fix typos and inconsistencies.

I then looked around for templates that I could use to ensure that key data is present for various audiences, such as emergencies or finding out what is where. Having found a series of suggestions on Reddit and blogs, I put together a small Markdown template that covered the questions what, where, why, how, and who? Having done some string manipulation as part of compage, I started with that before discovering Python’s Template class in string. The documentation is sufficiently small not to require anything larger really and I am just starting out on this road. That meant that I could then map the spreadsheet to Markdown and update the relevant repository.

However, having seen Lorna Mitchell talk about Vale, I thought that I would explore it to create a light weight checking pipeline. I picked up some silly typos and am sufficiently happy that it is something to develop in the longer term.

Was it worth the 3 or 4 hours writing? Well, so far so good. There is a large amount to develop as I go through this project and so many others. However, I am thinking of other projects and how that I write user documentation for varying audiences. This short post on technical writing is one to read I think as is the reference to Diataxis as a reminder for the types of piece to write.

No Comments

Leave a Reply

Your email is never shared.Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.