Documentation is probably one of those parts of IT that everyone agrees is important, but it isn’t always the first thing that gets done.
There’s usually something more immediate.
A user has a problem. Something needs investigating. A device needs rebuilding. Someone needs access. A customer needs support.
You fix the thing, the user is happy and the ticket moves on.
Then you remember that the documentation probably needs updating.
Earlier in my IT career, I probably saw documentation as something to deal with after the work was finished.
The more I’ve worked with processes and documentation, the more I’ve realised that it is actually part of the work.
I’ve seen what happens when documentation doesn’t match reality#
One of the better examples of this for me has been working on Joiner, Mover and Leaver documentation.
The existing process contained legacy steps relating to systems and administration that were no longer part of the current environment.
On paper, the process was there. The problem was that parts of it no longer reflected what actually happened.
Someone who doesn’t know the environment very well could follow the document exactly as written and still end up doing something that isn’t relevant anymore.
The document hadn’t necessarily failed because it was badly written. It had failed because the environment changed and the information didn’t keep up.
That was useful to see first-hand. It made the importance of keeping information current much more obvious to me.
Writing something down can expose problems#
There’s another thing I’ve noticed when working through processes.
Sometimes you don’t realise something is unclear until you try to explain it.
You start writing down the steps and suddenly find yourself asking questions.
What happens before this? Who is responsible for this part? Does another team need to do something first? Where does this information come from? What happens if that step doesn’t work?
Those questions can reveal that the problem isn’t necessarily the documentation. It might be the process itself.
That’s what I find interesting about documenting work. It can force you to look at how something actually happens, rather than how you think it happens.
Working in an MSP makes that even more important#
The other reason I’ve become more conscious of this is the environment I work in.
I’m supporting different customers, technologies and ways of working. I’m not always going to be the person dealing with the same issue next time. Someone else might pick it up.
A different team might need to understand what has already happened.
I might not even remember the details of something I worked on several months ago.
Useful documentation gives the next person somewhere to start.
It doesn’t replace experience, and it doesn’t mean every possible scenario needs to be written down.
It just means useful knowledge shouldn’t exist only in someone’s head.
What makes documentation useful?#
I’ve seen documents that technically contain the information you need, but finding the useful part isn’t particularly easy.
I’ve also seen information that was accurate when it was written but became less useful as the environment changed.
For me, the question has gradually become much simpler: If I needed to do this tomorrow and had never done it before, would this actually help me?
If the answer is yes, it’s probably doing its job.
If the answer is no, it probably needs some attention.
That doesn’t mean every document needs to be rewritten from scratch.
Sometimes it’s a small change.
Remove an old step. Clarify something. Add the information people keep asking for. Make the order of the process clearer. Point someone towards the system or team they actually need.
Small changes can make a document considerably more useful.
Documentation is part of the work#
This is probably the biggest change in how I think about it.
If I’m investigating an issue and discover something that another engineer would benefit from knowing, that’s part of the work.
If I’m reviewing a process and find that some of the information is no longer accurate, fixing that is part of the work.
If I’ve had to work something out that isn’t documented anywhere, there’s probably some value in leaving that information behind.
The person dealing with the problem next time shouldn’t necessarily have to repeat the same investigation just because I happened to be the person who found the answer first.
ITIL has given me a better way of looking at it#
My ITIL studies have given me a better framework for understanding something I’d already experienced in practice: useful knowledge needs to be available when it’s needed.
When information is clear and current, it makes the work easier.
When it isn’t, people spend time trying to work out what should already be known.
I don’t need to think about ITIL terminology every time I update something. It’s just something I’ve experienced through the work.
The course has given me a better way of understanding why it matters.
I’m not trying to document everything#
There’s a danger of going too far with this. I don’t think every task needs a ten-page procedure.
Sometimes the useful information is a few lines. Sometimes it’s a checklist. Sometimes it’s a knowledge article. Sometimes it’s simply making sure the right person knows where something is recorded.
The important thing is that it helps the person who needs it.
I’d much rather have a short, accurate document that someone actually uses than a huge document that nobody wants to read.
The technical fix isn’t always the end#
When I first moved into IT, I was mainly thinking about solving the problem in front of me.
That’s still important.
But now, if I’ve had to work something out, or I’ve noticed that a process doesn’t quite match reality, I’m more likely to think about what should happen with that information afterwards.
Should it be documented? Does something existing need changing? Would another engineer benefit from knowing this? Is there a wider process issue behind the problem?
Sometimes the answer will be no.
Sometimes it’s just a small update.
But I think that’s the difference for me.
Documentation isn’t something I want to produce just because I’m supposed to.
I want useful information to be there when someone needs it, so the work is easier and the next person doesn’t have to start from zero.
The technical fix might solve today’s problem.
Good documentation can make tomorrow’s problem a little easier.