The dreaded D word – Documentation (Part 1)

The dreaded D word – Documentation (Part 1)

Yup, for most techies, the dreaded “D” word. Give most admins a new network or a new server to install and they’ll leap to the task. Ask them to document the work they are doing and you can hear the groan.
I’ve decided to use this post to delve into the advantages of Documentation to try and change your mind.


Straight to the point, why on earth should you do documentation? Well, I’m not here to lecture you on any possible expectations for your role or any other nasty managerial reasons, so instead how about some selfish reasons?

Easily repeatable

So you’re setting up another Foo server for the n’th time. You’ve got a number of steps that need to be followed to have the server configured as required. The task is manual, long and dull. Plus you may be a little hung over from the previous night’s Mac Meet Up. Also, you’re human.
In this scenario, it can be easy to make mistakes, or to forget steps, possibly a crucial step that isn’t obvious until the server is fully running. With some form of documentation, this can form a nice and simple task list to work through, ensuring that you don’t miss any steps.

Knowledge Share: Delegate the task

AKA: Palm the task off to the next person down the departmental ladder.
With documentation, it makes it easier to off-load tasks to a more junior member of the team freeing you up to do more technically demanding (or less boring) tasks. Without documentation, it would be trickier to, *ahem*, delegate the task.

Knowledge Share: Teaching others

Having a decent set of documentation can help form internal training materials or lesson plans, allowing other members of staff to educate themselves on solutions and configurations they may not be familiar with.

Knowledge Share: Take a holiday!

The real reason these three are lumped together: The more people who have decent documentation on a task, the less only you can do. The less you need to do, the easier it is for you to take a vacation!

Mentally closing a project

This one is a more mental benefit, and possibly one unique to me, documenting all of the work I’ve done on a project helps me to brain dump all the potential items out of my head and mentally shelf the information, or clear the decks, helping me to be refreshed and ready for the next one.


My favourite word and the end goal of most Administrators. It is very difficult to automate a task if you don’t know (or can’t remember) the steps required for a task. Once you’ve got the documentation, you can build the automation. Once you’ve got the automation, you free up time and brain power for more things. The free time / power can be used to automate more things, and the cycle continues.

Why Not?

I can’t do the Why, without the Why not.

It takes too long

The time taken on the documentation can be directly dictated by the detail in the documentation. Personally, I know it’s not what you necessarily want to hear, but I’d always take as long as needed to get the documentation right. But on the flip side, short documentation is better than no documentation and if you’re tight on time (or patience) then write as much as you can, but schedule some time to return and ‘complete’ it.

It’s dull and boring

Generally, yes, I’d agree with that. But one thing I’ve found is that the better documentation I complete, the less questions I get from colleagues and customers when I’m in the middle of other projects / vacation / the pub. Of the two options, I know which I’d prefer!

Very little reward

Typically I’d agree. Completing a perfect piece of documentation, just to know it’ll get less attention or thanks than a server install (even though it is possibly just as important) can suck the motivation right out of you. Then again, I have had a few customers be pleasantly surprised by good documentation, even going as far as basing recommendations around it. And hey, at a minimum, being able to tell a customer “if you could check out page X of the documentation you’ll find the answer there” is great.


There you go! I hope to have at least caused some of you to stop and think about the advantages of good documentation, or even to start work on some of your own. Maybe next time I’ll look into the various types, and some possible hints I’ve used to help you along the way
As always, if you have any questions, queries or comments, let us know below and I’ll try to respond to and delve into as many as I can.

Further Reading

Most of this blog is from my own experiences but I can’t lay claim to it all. If you’re looking for further advice or reading around the subject of documentation and time management in general, I’d highly recommend reading:
“Time Management for System Administrators” by Thomas A. Limoncelli
ISBN-10: 0596007833
ISBN-13: 978-0596007836