Syadmins: Poor documentation is not a job insurance strategy

If you think you can get away with poor, little, or no documentation forever, keep reading. This article dispels this myth. A sysadmin who views documentation as painstakingly annoying—or a waste of their time when they have so many fires to put out—often produces poor documentation. The lack of attention to detail, or their inability to create reproducible written product consistently, diminishes their job security.

What constitutes documentation?

Sysadmins are responsible for carrying out a variety of fun and challenging tasks daily, and an inevitable one is troubleshooting. Documentation should function as a recording or history of a past event or situation. There is no greater time for proper and detailed documentation than when troubleshooting.

You should document both the root/cause analysis and the finer details. For instance, if you experienced an outage of some kind, your forensic investigation should contain the symptoms, deduction, and reasoning that led to your diagnosis along with the steps you took to solve the issue, the people that were involved, etc. Typically, a ticket is created any time a problem or incident takes place, so there on the ticket is where the information should be stored.

Also, good documentation helps the most important person in the process: you. It standardizes processes and makes them repeatable. Who wants to be called on Friday night while they are sipping tasty beverages in order to help a team member, when they can send a junior admin on the night shift to read the wiki for the repeatable, documented process they used six months ago? And who can remember what happened six months ago when you have tickets coming fast and furious right now?

"A short pen is better than a long memory any day."

Methods of documentation

Documentation can come in different forms: wikis, knowledge bases, a ticketing system, a GitHub repository, Google Docs, etc. The goal of any documentation is to be thorough, succinct, accurate, human-readable, and actionable. Your documentation should be able to be repurposed, especially when troubleshooting, as the same issue could occur for another sysadmin in the future. Your documentation or paper trail should allow that sysadmin to apply the information provided and come to a resolution without much difficulty.

Say that during another incident, it was reported that a system would not boot. You identify the symptoms and develop a hypothesis of what the problem is. Then, you take steps one, two, three, and four to solve the issue. All of these details should be documented, along with your finding that the hard drive had bad sectors, for instance. You might put this information into the body of the ticket, or it can be stored say in a knowledge base or wiki.

Poor documentation vs. good documentation

Your emotions and feelings go into writing, so if you hate writing documentation and see it as a nuisance, it will show in the quality of your writing. If you don’t establish a good relationship with writing and documentation, this could negatively impact your reputation and your job.

The number one example of poor documentation is no documentation at all. As a sysadmin, documentation is a daily task. While it may be your least favorite thing to do, it is an important piece of your job security. Another example of poor documentation is documentation that is difficult to follow, or vague in its description or explanations. If the documentation leaves someone asking more questions or does not answer the questions it’s supposed to answer, that is poor documentation.

Poor documentation is also confusing and frustrating. It builds silos and potentially walls cross-functionally. Poor documentation is tribal and results in bottlenecks. If your documentation is poor, you will be asked to rewrite it, and by then you may have forgotten details. Why not do it well the first time? Don’t make extra work for yourself.

Writing documentation is also an effective way to think through the critical details of a technical subject. As a sysadmin, you should develop a healthy relationship with documentation as it could position you for promotions, interesting new technical opportunities, publication, etc. The better your relationship, the higher the quality of your documentation.

One of the benefits of good or great documentation is that it provides help to someone else, whether that's your fellow teammate, a customer, or someone else—maybe even your boss. Good documentation is transferrable, insightful, clear, and concise. It increases skill and reduces knowledge gaps, and is more reusable and understandable. Good documentation helps solve problems and even breaks down silos.

Documentation bandwidth

If you work at a company or organization for a long period, your documentation will likely go out of date. How much shelf life your documentation has depends on the churn in your environment. One way to allow your documentation to travel is to use source code management (SCM) tools such as GitHub or GitLab. That way, changes can be updated regularly.

For example, if you write a script as part of your documentation and you don’t touch it for a year, your recollection of what the script does or is doing will fade, and you will spend more time reworking or remembering how it works. This situation is a clear waste of your time. Maintaining the script in some form of source control with lots of comments is a nicer and more effective alternative.

How to improve your documentation

Improving your documentation skills is a better job insurance strategy than being stuck in a disillusioned state of mind that says that documentation is not important. In this type of situation, you will end up producing low value, mediocre material that serves no one. Even if you are performing at a high level in other areas, your poor documentation could overshadow that fact.

Writing is critical to being a sysadmin. It’s definitely in your best interest to work on improving in this area. Believe it or not, reading actually makes you a better writer. The more you read over time helps your writing improve, so read technical books and other related material. Also, the more you write, the better you become at it. Find time to write regularly, such as writing a blog, publishing articles, or writing whitepapers. Another option is professional training, of course. Linkedin Learning, Pluralsight, and Udemy offer writing videos and courses.

Invest time into writing, just as you do for increasing your technical knowledge. You will improve your job permanency because others avoid documentation like the plague, meaning that you will become the sysadmin whose documentation helps put out fires fast, improves collaboration, and teaches others. You will also ensure that you are indispensable, and you can take pride in all areas of your sysadmin work. Writing is like doing push-ups: The more you do them, the stronger you get!

Conclusion

So if you think you have a choice when it comes to documentation, you are wrong. Don’t perform your job duties halfway. Make it a point to put in the time and attention that documentation deserves. You will be better for it, and so will the others around you.

You always have a choice: Document, or become irrelevant.