The importance of documentation (and why you shouldn’t hate it)

DocumentationDocumentation. We all hate the process don’t we? While there is something gratifying about seeing a polished piece of technical documentation, the long and often times arduous task of creating, editing, proofing and validating steps can cause any systems administrator to curl up in a ball under his or her desk.

Recently I accepted a position with a new company and gave my two weeks notice to my current employer. Immediately there were requests for documentation. Like many large corporations, the “silo effect” was common and therefore not much cross-knowledge was achieved. Begrudgingly, I began the mundane task of step by step process writing not only to leave the other engineers with a body of work to help them along on things they might not be familiar with but also to allow myself the “good feeling” of leaving a company knowing I have shared as much as possible with my former teammates.

Another engineer on my team long ago created a “Linux Wiki” page that until recently, I hadn’t really spent much time in. I decided my documentation would be best served along side that of the other engineer’s entries. As I began deciding how best to present my data, I actually began enjoying the process. Writing in a wiki style can be “fun” once you get used to how formatting works within the wiki application.

I found the following very useful:

  • First and most importantly, understand what you are about to write. Writing about something you are not familiar with will only serve to confuse those reading it.
  • Pretend you are writing for a five year old. Do not assume those reading it will know about whatever shortcut you are about to mention. If you need them to enter a directory, tell them “cd /etc”. This doesn’t mean they are stupid or incapable of simple tasks, it just takes out the possibility of mistakes.
  • Ask your peers to proof-read. What you think is amazing might be confusing and your peers will let you know. Don’t take this personally, after all they are the ones who are going to have to read what you write.
  • Link to external sources or other wiki entries on the same system if you used them. Nothing is more annoying to a reader than reading “I found this great blog where so and so explains exactly how to compile such and such” and no link is provided.

You want me to write individual steps? %$#@!

I believe I actually said this, or at least thought this when the request came in. “Write it so Barbara in accounting could do it”. My argument, which at the time I thought was valid was “If someone reading this doesn’t understand how to log into a database, why would you want them issuing DELETE statements on that database?!” In some senses the argument holds water but let me explain.

Writing step by step technical instructions is mundane. Let us agree on that. It doesn’t mean those reading it are incapable of doing their job, it just means that something easy to you might be new for them. You’ve learned new things, right? Wasn’t it easier when you had step by step instructions for something extremely involved? The guess work is taken out when you write steps. Your reader may skip them or they might use them every time but either way, you are helping them form a basis of understanding about whatever you are writing about.

Why should I write this? I’m leaving in two weeks!

Plain and simple, that attitude sucks. The open source community lives and breathes on documentation. When I got started on Linux in the mid 90’s, “How-To’s” were gold and still are. Download any piece of open source software, unpack it and you are bound to find a README file. This is all documentation and chances are you’ve read one and have been assisted through some issue by one. Leaving documentation for the next person to fill your role or your former teammates is not only respectful but should be part of your psyche as a systems administrator, engineer, etc. You are in the open source profession, you should WANT to share your knowledge!

Leave a Reply

Your email address will not be published. Required fields are marked *


You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>