Skip to main content

Sysadmins: How do you think about documenting procedures?

Tips for documenting procedures from complex technical tasks to simple handwashing.
Image
person writing instructions

Photo by Ketut Subiyanto from Pexels

Where, if ever, do you find yourself documenting procedures?

148 votes tallied
Home
7 votes
Work
52 votes
Both
66 votes
I don't document procedures...ever
23 votes

These days, everywhere I look, I see procedures and documentation explaining how to complete a task. It's everything from a recipe online for a delicious coq au vin to instructions on how to wash your hands in a restroom. Our businesses are no different. If there is a task that you have to perform, chances are, you'll need to explain it to someone else one day. Companies want their employees to document these processes. I can't tell you the number of times that my division wrote procedures for various tasks while I was a submariner. After that, when I worked in support, if I fixed a unique issue, it was expected that I document the fix afterward. Here are some tips for helpful documentation that I picked up along the way.

Taking notes

The first time you sit down to write the procedure, I recommend performing the actions and taking copious notes as you go. Include a lot of details. This makes your instruction comprehensive and allows the user to easily follow along. You really want to over-explain here; then, when you go to draft the actual procedure, you'll have all of the available information and can cut away the unnecessary bits. The goal is to be thorough, but concise.

Placing notes

Anytime you need to provide additional information about the output or consequence of an action, it is preferable that you provide the note prior to the action so that the user can make the correct decision about how to proceed. There is nothing worse than carrying out a step in a procedure and then seeing a note about how you really should have used this flag or that option to get the outcome you desired.

Write to the new person

No, don't assume that your colleagues aren't smart. I know that not everyone is born with the same intellectual gifts, but that's not the point here. The point is, you should always write a procedure or how-to for the most junior person that could be using it. It doesn't do anyone any good if you write the procedure so that only your most senior systems engineer can read it, but everyone else has to ask for help. This goes back to the original point; you want to make sure to note every action, even the most basic ones.

Dummy check

Much like a writer uses a copy editor, a person writing a procedure should have someone else carry out the procedure independently. This way, the independent user can note where things don't work as described or places where you need additional clarity. With the expert there to guide them, you can fix any gaps in your explanations.

Get approved

This point will only get you as far as your organization requires. In some teams, anyone can write a procedure and share it. In others, it may require approval signatures from your boss, your boss's boss, and so on. For all of my military or government contractor people, it's not an uncommon requirement that procedures be signed by your department head and, potentially, the commanding officer. While this step can sometimes feel like a hassle or just "more red tape," it is definitely a good idea. If something goes wrong and you didn't get approval, you may need to refresh your resume. Be smart; get your procedures approved.

Take-away

I hope that you will find some use for these tips in your own life. These can be applied to your professional documentation and also your personal writing or blogging. If you ever wanted to write an article for this site, for example, these tips are a pretty good outline for how to get a "how-to" article started.

[ Free cheat sheet: IT job interview tips

Topics:   Documentation  
Author’s photo

Tyler Carrigan

Tyler is the Sr. Community Manager at Enable Sysadmin, a submarine veteran, and an all-round tech enthusiast! He was first introduced to Red Hat in 2012 by way of a Red Hat Enterprise Linux-based combat system inside the USS Georgia Missile Control Center. More about me

Try Red Hat Enterprise Linux

Download it at no charge from the Red Hat Developer program.