IT documentation nobody reads — and the kind that saves the day

Almost every company that has ever had an audit or changed IT provider has some documentation. Almost none of it is used.

The reason is always the same: the document was written to exist, not to be used. It runs to a hundred pages, is complete on the day it is written and out of date three months later, because keeping it current would be a job of its own.

This note is about what is worth maintaining so that it actually helps.

The usefulness test

One question settles whether a document has a point:

Could somebody who does not know this environment resolve an outage from it at two in the morning?

If the answer is “no, but they would know what the security policy is” — that is a document for an audit, not for work. Both have their place; they should just not be confused.

Four documents worth maintaining

1. A map: what sits where and what depends on it

Not a network diagram with icons, but an answer to “what stops working if I switch this off”.

The minimal version is a list with four columns: what it is, where it physically sits or which provider hosts it, what it is needed for, what breaks without it.

The value only shows during an outage, but then it is large: it shortens the guessing phase, which in an unfamiliar environment can take longer than the repair itself.

2. Access: where it is and who holds it

Not passwords — those belong in a password manager. This is a list of places you need access to at all: the domain panel, the hosting panel, cloud service consoles, providers, device administrator accounts.

This is the document whose absence hurts most when whoever ran IT leaves. Recovering access to a domain registered to somebody’s personal address can take weeks.

3. A decision log

The least often kept and the most underrated. A few lines with every significant change: what was changed, when and why.

“Why” is the only part that cannot be reconstructed from the environment later. In two years anyone can see there is a firewall exception — nobody will know whether it is still needed. Without that knowledge exceptions do not get removed, only added.

This document costs a minute per change and saves hours at every review.

4. Short instructions for users

One page per topic: how to connect to a network share, how to report a problem, what to do after losing the phone with the authenticator.

The value is measurable: these are the things people ask about most often, and the answer is the same every time.

The rules that keep it alive

Keep it close to what it describes. Documentation in a separate system with its own login does not get updated. Text files in the repository, or pages in a tool the team already uses, stand a far better chance.

Update at the change, not at review time. A note written while making the change costs a minute. Reconstructing the same thing six months later costs an hour and comes out worse.

Write for somebody who does not know this. Shorthand that is clear to the author is useless to a successor — and documentation exists precisely so the successor does not start from zero.

Record the odd things. An exception, a workaround, a machine that must not be updated, a device with a non-standard setting. This is the most valuable part of any documentation, because it is the only part that cannot be inferred.

One thing worth saying plainly

Documentation of an environment belongs to the company, not to whoever maintains it. If the end of an engagement leaves an empty folder and the knowledge inside somebody else’s head, that was not a service — that was a dependency.

That is why I treat it as part of the scope under ongoing care rather than as an extra. The test is always the same question: could somebody else handle this environment without calling me.