Documentation & Planning – the sneaky skills

One of the biggest issues I’ve come across with the places I’ve worked (and the people I’ve worked with!) is lack of ability to document and to plan. It seems that this is a much maligned and skipped skill that many just don’t have. This post is about how I do my documentation and planning, which I hope could help others who really don’t know where to start.


Why document?

Okay, so let’s get this part out-of-the-way first, so that you understand why it’s important before moving on to how.

Documentation is incredibly important – it’s a much maligned skill. And it appears to be missing from a large number of admins who just don’t seem to care that the knowledge they have exists only in their heads.

I have previously written at length about why documentation is important, so I won’t go over all of it except to say two things:

  • Documentation is the information that allows you to take uninterrupted weekends/breaks/holidays
  • If you have to tell someone how to do something more than once, you need to write it down

How to document

If you’re new to an environment and there’s no documentation, there isn’t really an easy “this is how you document everything” guide. It’s a bit harder than that.

From personal experience, the best way is to start with your infrastructure – what servers do you have, what do they do. Document everything about them. Move outwards from that – what’s your networking like, what VLAN’s do you have, what subnets are available. Look at your directory and identify management – how does it work, what types of users do you have, what types of groups, are their special cases etc.

As said above – if it’s something you’d need to tell someone more than once, it should be written down. Document as if you were going to have to hand this environment over to someone and they wouldn’t have you around to fill in the gaps – your documentation should do that.

Wikis are your friend

I don’t really care what kind of wiki is your personal wiki of choice, be it Confluence, MediaWiki, DokuWiki…whatever. But a wiki works with the kind of information we have to deal with. Information that can have multiple types – for example, where do you put that piece of information on how to fix that troublesome piece of obscure software? Does it go under ‘Software’? Does it go under ‘Servers’? Does it go under ‘Troubleshooting’? This is why tags/categories help – because then it can fit under all of them!


How you structure your documentation is purely personal – it’s up to you (if you’re a solitary sysadmin) or your team as a whole (if you’re part of a team). You just need to make sure it’s logical to you. Some people prefer to use some kind of breadcrumb structure, which many wikis now have either built-in or as an add-on/plugin. If you and your team need this, then use it. If you prefer to search to find your information, wikis certainly accommodate that (though some accommodate it better than others).

Make it “idiot proof”

When you’re writing documentation, you want to write it in such a way that someone else can come in, pick it up and run with it. Not just any Joe Blogs off the street, but someone with roughly the same level of technical experience.

I’m big on dot-points. Very big on dot-points. They’re short. Succinct. To the point (ha!). They flow well. And for instructions, they work. They are also very conducive to “idiot proof” documentation – because you can literally outline every. single. step.

An example of my idiot proof documentation can be found here – Building up a Logging Server – OSS Style! – which I wrote for my work, but then modified slightly so that other Windows administrators could easily follow it and deploy ELK in their own environments. It’s by far been one of my most popular blog posts that’s still accessed numerous times a day by people searching for how to do something.

Test it

Once you’ve written something down, that’s awesome! That’s great! But…what if it’s not right? What if you missed a step? What if you’re setup is slightly different to someone else’s so your instructions or documentation don’t run the way you originally witnessed.

It’s incredibly important to test your documentation and the easiest way to do that is to give it to someone else within your team to look over and verify that it’s correct. Get them to test it by going through it step by step – this part is easier if they’ve never seen the system before as it allows you to see how much information you can impart…and what vital piece of information is missing that’s required in order to operate/install/configure the system you’ve documented.

Be prepared for criticism. Do not take it personally. Take it, use it, and improve your documentation.

Set a ‘use-by’ date

No piece of documentation is everlasting. It will always need to be edited at some point, revised or (in some cases) completely removed/archived because it’s no longer valid.

You need to make sure you set use-by dates on your documentation. Because without it, you’ll just end up with a whole bunch of information that might be valid when it was written…but is utterly useless 12/24/36 months down the track.

Most pieces of technical documentation should be reviewed yearly, if only just to do the once over of “Yup, that’s still correct”. Some other pieces might need to be reviewed more frequently, depending on what they document (e.g. staff contact lists, rosters etc.)

This can’t be done by one person alone – it needs to be done by the team as a whole. Much as you can have “Password Hell Day”, where all the passwords are changed; I propose having a “Documentation Review Week”, in the quietest part of your year (for us, that’s December) for everyone to go through the documentation and weed out what’s no longer needed or edit those that have become out of date.


Why Plan?

Surely this is a no-brainer. Planning is incredibly important. Without it, things just wouldn’t go…well…to plan!

The main reason for planning is to ensure you’ve covered all your bases – to make sure you’ve got your contingencies covered and your shit organised.

There are two types of planning – daily work planning and change/project planning.

This is mainly going to focus on the change/project planning, as daily work planning is fairly personal. For those interested, my personal choice is a product called ToDoist which I wrote a piece on last year.

So – onto change/project planning.

Write down every step you’re going to need to do – EVERY. SINGLE. STEP.

This may seem pointless and over the top, but it’s important. Write down every single step you’re going to need to do. Double check it. Guarantee you that you’ll think of something you’ve missed. Or you’ll realise you’ll need to reorder the way in which you’re doing things. Or you’ll figure out that someone else needs to be involved.

Writing down everything you need to do means that you make yourself aware of all the bits and pieces that are involved. As you’re writing it down, you may realise that you’ve forgotten some steps and need assistance. Or that there are parts that you can’t complete and that you’re going to need to hand off to someone else.

It also means that you have given yourself a check list. When you’re doing important changes, these are lifelines – because it can be so stressful when you’re in the middle of a critical change, to make sure you’re doing everything correctly. Or worse, when you’re having to make the change at 2am in the morning, because that’s the only change window that was available.

I get given so much shit for my spreadsheets and to-do lists, but they are the reason that my changes go through smoothly. Dot every i, cross every t. Try and see the big picture. Make sure you’ve covered everything.

Change is 80% planning, 20% doing. If you’ve planned well, the change will go well.

Speak with others who will be involved

No change is done alone. Even if it is only you doing the work, there are bound to be others who at least need to know. Communication is key.

For those who are involved – make sure they know what’s happening. Give them the list of what needs to change. Make sure you highlight their roles and responsibilities. Make sure everyone knows what their roles are.

For those who aren’t directly involved, but need to know – be short and to the point. Give them the information they need as efficiently as possible. The more extraneous information you give them, the more likely they are to forget.

Check your dates

If you want to do something on a specific date – please, check the availability of everyone/everything you need.

Sometimes you plan changes with all the best intentions in the world and organise for a specific date/time…only for it to fall apart because there’s something else on (like a power outage!) or someone you need who isn’t available (because someone’s getting married!).

These things need to be checked in advance – so plan ahead. Work out what dates you can do the work on. Speak with the people involved. Check your change calendars (if you have one) or check your email to see if there’s anything that might adversely impact your change – or worse, something that your change will adversely impact!

Once you’ve got all your ducks lined in a row, you can then proceed to schedule your change/project with the knowledge that everyone/everything you need will be available.

Work with change-control – not against it

ITIL can be incredibly frustrating. It can – there’s no denying it. But it can also be useful. In situations when you’re planning a change/project, you want to use all the tools at your disposal – and that includes change control.

The change control process that we follow is pretty standard – what, when, who, how, why.

This is why you plan everything in advance – so that when you get to this point, you have all the information to hand and you don’t have to worry about your change being rejected due to lack of information.

If you plan well, change-control should be a breeze.


So there you have it – documentation and planning…the sneaky skills. If you can get a grip on both, it will make you that little bit better at doing your job well!


Leave a Reply