You Should Be Documenting
I’m writing this after being burned by poor documentation.
This isn’t the first time i’ve felt this, but this time it isn’t my own direct fault. There is some blame to fall on myself though, I will admit that. That’s part of working with others.
Working in IT requires thorough documentation. Speak to any IT person and they’ll wholeheartedly agree. And yet they won’t do it properly. I’m guilty of it at times as well.
Why?
Most of us have exclaimed one of these at some point in our career:
What host did we install the server on?
What is the server’s IP address?
Where is the config file for our application stored?
What are the Domain Account Group Memberships required for this application?
What Group Policy did we enable?
Why is that Port open in the firewall?
Who built this system?
Yeah, I know. You can go look it up on the server, or on the Virtual Host, or in your configuration management system.
But then one day you will need the answer to the question, and you won’t be able to get onto the server, the Virtual Host, or the configuration management system.
Good thing you wrote it down. You wrote it down, didn’t you? Oh wait, here it is, but:
The document was last updated in 2010.
The document is missing some parts, so you can’t trust it any more.
The document was made by someone notorious for poor documentation.
The screenshots don’t match the text. Which one is correct?
I see this really as a problem in our perceptions of documentation.
Documentation is more than a how-to. It is a Historical Record. It is a critical part of Configuration Management.
We get tasked to write documentation when we build new systems, integrate them, perform tests, troubleshoot, create user guides, and so forth.
We grumble about how much time it takes. How we just want to get the job done and move on to more exciting things.
You know what takes longer and is totally not exciting at all? Doing the whole job again.
Give any IT professional a task to do, and then ask them to repeat what they did a month week later. Guaranteed they’ll get it wrong the second time, or do it differently. I get that way sometimes a day later after doing a task, but maybe that’s just my sporadic brain.
How do we all experience the burn as early as possible?
The problem is, we don’t truly fathom what value documentation has until its too late. Until the server has accidentaly been deleted by your hosting provider. Until you’re expected to answer questions about a product to a customer, and your only point of reference is the documentation. Until we’ve created an unnecessary crisis, and we all gain a couple more grey hairs fixing it.
A question may be, how can we instill these values from as early as possible? How can we get burned to appreciate the importance?
Can we get the universities to try and teach new IT personnel to document well from the beginning? I had a taste of that at my Uni, but it didn’t really click at the time, because it wasn’t real. It didn’t hurt enough to realise I needed to change my practices.
I remember listening to a podcast (most likely a hanselminutes one) with a guy talking about how he gets his students to start a task in the classroom, and then everyone has to move halfway through to the seat next to them, and keep working based on the documentation created by the previous student. I thought this was brilliant.
However it does sort of not work with the ones that did document well. The ones receiving those documents will think this is great and they’ll continue to receive good documents.
I guess the only effective way will be to make students build some form of technical document at the beginning of a subject for a complex process, get them to then forget about that document for at least a month, and then assess them on the result of them trying to follow it at the end. I think this would sting a lot of people, and for good cause.
Or, perhaps the onus is on the companies/organisations. Maybe they need to crack down harder from the get-go. Unfortunately though a lot of us don’t see the benefit in applying more time to document better, as the effect can be delayed so far (oftentimes a year or more) that it’s disassociated with the cause.
Or, better yet, we do all of the above. Multiple nets all through the water will eventually catch the majority of the fish, rather than just catching half or less with a single net.
Technical Documentation Standardisation
I didn’t come up with this “standard” way of writing documentation, but it’s one I’ve come to love using because it is so effective, especially when I have to follow documents written this way.
The first part is writing each paragraph with a number at the beginning.
Writing each step with a number for the paragraph
Makes it so much easier to pick up which step you’re at
When you’re switching your focus between the document and what task you’re doing
Or if you need to tell someone what part of the document to start at.
Next, you should bold the actions that are required.
Don’t put it in “quotes”, or make it italic. It has to stand out from the rest.
Don’t bold the verb, bold the thing you’re meant to interact with, or the data to enter.
Like, click next, not click next.
This helps you see what you need to do at a glance.
- Also for lots of actions to perform at once: Indent and list the things to change
- Set Hostname: foobar
- Port: 12345
Don’t say “This screen will appear. Do this”. It’s just extra crap I don’t want to read when the pressure is on.
Put a screenshot after every possible paragraph. And put a red circle around what you need to do.
And, I can’t stress this enough, make sure the screenshot matches your text. If you can’t change the screenshot afterwards, get rid of it entirely. Mismatches make your reader lose trust in the integrity of the document.
Finally, for running shell commands, include a dump of the output into the document. Of course scrub out anything sensitive if the document could be made public.
Switching between your document and the task at hand is hard. Use these standards to cut down your cognitive load, and you will cut down on stupid mistakes.
That’s basically it. It’s really simple I think, and it creates amazingly easy to read documentation.