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