Recently I have been doing a lot of system admin type work and found a good process to improve my workflow and future maintainability of these workflows. We all know it can be painful to keep track of everything we do, but the small percentage of extra time used for documenting steps and thoughts, become exponentially more useful as time goes on. It really something can give you an edge in terms of a fast and slow outcome. There are a few styles and approaches to documenting which I will describe and elaborate over.

Ad-Hoc

One process that I found extremely useful is when working in the terminal is to constantly write down commands you have run in a general note. In a lot of cases if your field is not overlapping with the workflow you will rarely see these commands again and will need to research them, so after returning after a while you have a document ready for reference.

As an example I was recently investigating some ACPI issues on my Laptop recently and documented each link I read or command I ran. Which allowed me to re-reference steps a bit later for faster investigation. When debugging technical issues like these it helps to stay procedural otherwise steps get repeated and you are wasting time.

This is also extremely useful if the configuration setup has extra steps that need to be taken, for example installing external dependencies. Very commonly know as development documentation such as a CONTRIBUTING.md file where each development step is listed out. It's also possible to self document would this by using something like a Makefile file and having an alias for each command in there, while this adds convenience, it easily can be used for reference as well.

Mental Notes

As software evolves different solutions appear and disappear. It's very hard to make these kind of things self documenting. For example certain bugs might have band aid solutions which will appear obvious at first, but as time goes on that will become much more blurry. Maybe the bug gets fixed and the temporary fix can be removed, but much time has passed and therefore an unnecessary workaround remains or you come back a year later to refactor a module, but remain baffled on why that piece of code is that way.

There are many more examples like this, as software is a complex tangle of ideas and implementation. No matter how much care you take in implementing patterns, after a certain point the cracks in the foundation will show and that's why extra care needs to be taken when approaching these problems and documenting between blurry lines.

Having encountered such problems before I find that comments in the form of breadcrumbs in code, commits or pull requests give leniency too make such updates smoother in future iterations. This kind of documentation will mostly be inline code comments, which should be concise and to the point and should be used liberally.

General Documentation

When writing general documentation its very helpful to stay with guidelines and keep it as targeted as possible. A great framework to follow for this is Diátaxis which outline four key sections within the framework. Tutorials for teaching beginner content to a user. How to guides for teaching specific tasks. Reference for technical descriptions such as an API reference. Explanations for understanding key concepts within the application.

A great reference which follows is the Python documentation where my favourite part has always been the how to section, these articles always have given me most enjoyable, fastest and cleanest learning outcomes

There are many more ways to document and help a user or developer exploring the tool or library. For further reference the a aforementioned Diátaxis is great for quick bites, but otherwise the book Docs for Developers is great for a longer read, especially if you are just trying to start your documentation journey.