Having spent the last 6 years in an administration/engineering role, I have learned a number of important lessons and developed a few techniques that have helped me write documentation in a clean, consistent and usable way.
This list is not meant to be a comprehensive solution, but more of a guide that allows you to pick and choose the pieces that are important or applicable in your environment and improve your documentation. Even if you already have a firm grasp on your documentation skills, I believe in looking for new and improved ways to do things — the more you know, the better.
Documentation Pitfalls
Before getting into any specific tips and techniques, I’d like to highlight a few thing to be aware of if you are working on improving your documentation skills. These pitfalls come up time and again, so understanding these problems as they develop (or even before) will enable you to correct issues more quickly and focus on things that will give you the most benefit.
1. Your Docs Get Stale
If you work anywhere for long enough, your documentation will go out of date. The faster your organization moves, the faster your documentation will become obsolete. This is frustrating if you are attempting to get something working from a doc that you or a team member wrote at one point but no longer works because of the churn in your environment.
A nice alternative to this is by automating things via code or scripts and maintaining it in some form of source control with lots of comments. See “Making a Github Repo” in the tips section for more ideas.
2. Not Leaving Comments in Your Code
This might be the most important item and should be a familiar concept for developers, even though sometimes they don’t follow this philosophy. If you get into the habit of writing scripts or code it is incredibly useful to be able to write a very brief and concise comment to explain, 1) what the code is doing and 2) why the code is doing it.
If you write a script and don’t come back to it for a year, the chances are very good that you will not have any recollection of what it is doing, and you will likely spend more time than you would like reworking or remembering how things work.
Take the following snippet for example:
This is a simpler example, but unless you write bash scripts frequently, it is likely that you will have no idea what this does right away. Compare this sample with the following commented example:
It is much easier to understand what is going on here. If somebody else ever has to maintain this script, they will be able to walk through what it does and not spend extra time trying figure out its purpose.
A good script might have a brief summary of what it is doing and why, an author and date, along with liberally sprinkled comments explaining what is going on in various parts of the script or if there are any particularly tricky logic or commands.
3. Documenting Unimportant Things or Superfluous Info
Another pitfall you might run into is documenting things that aren’t important. For example, recording a series of commands that you ran that one time probably isn’t worth documenting; it is much better to make a script out of it and put a few comments about what exactly the script does.
Conversely, sometimes writing down frequently used commands can be useful. More on that below.
4. Documenting Superfluous Info
Recording superfluous info or docs can become another issue. Some information is so common that it is almost certain the first 2 or 3 hits on Google or Stack Overflow will have the solution you are looking for. Therefore, you are mostly just duplicating work by documenting information that is easily accessible.
For example, it is just as fast to search Google for looking up programming language syntax or trivial commands rather than writing them down. In the code snippet above, I was having trouble remembering the syntax for a bash for loop, so it took a few seconds to Google “bash declare and assign array” because I knew exactly what I was looking for.
Learning to use Google and Stack Overflow effectively is a different topic, but here was the first result I found that helped me get unstuck:
It is important to find your own balance for knowing what to document and when, but that will mostly come with experience and time. It is much easier to remember topics when you work with them frequently.
Documentation Process Tips
Now that we have addressed some of the most common pitfalls with documentation, there are a number of tips and tricks I have discovered that help. Let’s take a look at the most important ones.
1. Find a Good Note-Taking Tool
I like to use Microsoft OneNote because it works on Windows and Mac, and even has an online version for Linux users. OneNote functions sort of like a wiki for any of my personal notes and thoughts. OneNote is also great for organizing thoughts and notes into different notebooks and topics.
OneNote also has good search capabilities, which makes it easy to find notes that might be buried.
Oftentimes when I take notes, instead of copy/pasting an entire block of text from a site, I will paste the link and make a note about what is going on in the link. It works almost like a shorthand, the more you use it, and cuts down on extra clutter in your docs, making it easier to find a particular fix to a problem.
Here is a sample of some “shorthand” notes I recently took:
I can do a quick search for any of those keywords and quickly find instructions on how to fix the problem. This shorthand, coupled with detailed explanations and commands, makes your notes more convenient and powerful.
Another advantage of taking quick notes is that you’ll be able to locate information more quickly if you run across a problem you have solved before instead of having to look it up on Google, which can take much longer.
If you want to share notes or notebooks, OneNote also has the functionality to share with others if you don’t want to run a wiki or deal with shared docs.
Wikis are also a good option, especially if the notes or docs need to be shared with others. Github has a nice wiki feature, especially for collaborating on specific projects. When using wikis, be aware of outdated docs when using any kind of internally-hosted documentation, especially if you didn’t write them.
2. Make a Github Repo for Difficult-to-Remember Commands
If you work a lot with a technology and find yourself needing to run a series of commands more than once, it might be beneficial to document those commands somewhere, or again, turn the commands into scripts.
The best rule of thumb for deciding which commands to document and which not to comes down to how often you need a command.
Here are some example Docker commands from the Github repo I have been maintaining:
The most effective approach I have found to alleviate the issue of where to store frequently accessed commands is to record the most useful ones in a Github repo (https://github.com/jmreicha/oneliners). This technique has served me well for things like one-off or complicated commands that aren’t very easy to remember.
Using a repo for documentation is great because it has the added benefit of tracking the history of the commands you record, and it is also public so others can benefit from the commands or can add in their own. Most of the time, it is good enough to have just a .md file in the root of the repo to keep track of frequently used commands.
However, if you wanted, you could take this idea one step further and translate commands into shell scripts and store them in your frequently used commands repo for extra awesomeness.
3. Write Blog Posts
It is a fun learning experience if you want to host your own blog. It is also a great place to write down and make documentation available for others, as well as yourself, for particularly interesting problems you have run across and solved.
There are a number of hosted blogging platforms if you’re interested in just writing, but not worrying about running a backend. Medium is good, Blogger is another one.
Another option, if you are committed to it, is to run your own blog. It is a great way to learn about operating a website and for logging your journey. If you decide to run your own blog, check out WordPress or Ghost, both are open source and have large communities.
Final Thoughts on Documentation Techniques for Sysadmins
Ultimately, these are just tips. Learning how to do document effectively is a much longer process that takes time and effort. These tips, and any others you may stumble across, will help, but it is important to develop your own style of documentation. You’ll want to do things in a way that makes the most sense to you and those you work with or who will need to consume any of your docs.
Let me know about your documentation techniques. I love learning new ways to improve my skills and find it interesting to see how others handle documentation.