Documentation – or as I like to call it “Information that allows you to take uninterrupted holidays!”

Maybe I was trained differently. Maybe my career in IT started off with a group of OCD people who were just fanatical about information sharing and we’re the odd ones out. Maybe I’m just nuts about writing stuff down. Truthfully, I wish more people in IT were like me, if only for the documentation skills (and because I’m awesome…but more for the documentation!)

I was told that the aim of a systems administrator is to make yourself redundant. Pretty harsh, but also pretty accurate. You’re there to fix things when they break, implement cool things to make things better and to make sure that everything hums along smoothly.

Fixing things involves going through a list of tasks to diagnose what the problem is – now, don’t get me wrong, troubleshooting is a lost (and almost intuitive!) art that you either have or you don’t. But being able to follow a list of simple instructions or hints does make finding those “tricky” problems easier. So why don’t more sysadmins write down the steps they used to fix something?

Installing a piece of software should be relatively straight forward, right? You should be able to pick up the manual that came with the software, install the software as per the manual and voilà! Working software! Sadly, it doesn’t always happen that way. Some software is written in house, some software doesn’t come with a manual, some software has been tweaked and fine tuned for the specific organisation or business that it is now so unrecognisable that no amount of instructions from the original vendor are going to help. So why don’t more sysadmins write down the steps they used to install such software?

I’ve got a few reasons – time-poor sysadmins appears to be the top one. Sadly, documentation is way way WAY down the list when it comes to priorities. We’ve got jobs to do, don’t we? Documentation often gets missed because it’s not seen as important, when it should be. There’s always more pressing priorities, more jobs to do, more phone calls to return, more email to read. Documentation should be a higher priority, but it isn’t. Why?

I feel like I’m about to be a bit harsh, so I’ll apologise in advance. From my point of view there are two major reasons why documentation isn’t seen as a high priority: mostly sheer laziness, but also selfishness.

Let’s face it – documentation really is one of the most boring, time consuming and sleep-inducing tasks we can do. It’s not interesting, it’s not engaging, it’s not sexy. It’s mind-numbingly dull. I honestly think a fair few sysadmins choose not to do it simply because they cannot be bothered. It’s just too much like hard work. There are always cooler things to do than documentation – playing with that new server, speaking with that co-worker, reading that (totally work related) website. That needs to change. Documentation should be something we do as often as possible – it’s the old saying “A little bit goes a long way”. Don’t sit and write pages and pages. Just do a little bit at a time…it’ll come together in the end!

Selfishness is an interesting one and I’ve only come across it a few times within my career. It always astounds me when I do. There are a few sysadmins who do not document what they do purely because they don’t want anyone else to be able to do that task. They want to make themselves indispensable. They want to ensure that they have knowledge that no one else doesn’t. In my eyes, this is selfishness and stupidity of the worst kind. Knowledge sharing should happen instinctively so that you’re not the only one that knows about that system or server or software package.

Documentation is there so that other people can pick up and run with whatever it is you were working on, or whatever needs their attention if you’re not around. Documentation should make it so that you can get sick, go on holidays or (using the standard IT cliché) get hit by a bus without frantic phone calls back and forth to get work done. While it’s lovely to be wanted and needed, it should never get to the point where you can’t take a day off without being required to provide information to work. It should already *be* there – in the form of documentation.

Take time to write down those steps you use to install that piece of software, take a few minutes to write a list of instructions for how to troubleshoot that insanely difficult problem you found on that server. In the long run, it’ll save you time and aggravation and you’ll be able to take holidays without needing to get that dreaded phone call “We’re trying to do blah, but you’re the only one that knows how. Can you help?”