The Complete Guide to IT Documentation

Every IT team has a person like this: the one who knows why the backup job runs at 2:17 instead of 2:00, which switch port is flaky, what the vendor support PIN is, and the exact order to bring services back after a power event. When something breaks, the room turns toward that person. When that person is on a plane, the outage lasts three hours longer than it should.

That is the real case for IT documentation. It is not about compliance checkboxes or a tidy wiki — it is about moving what the team knows out of individual heads and into a form that works at 3 a.m., during onboarding, and on the day your best engineer gives notice. Undocumented knowledge is not free; you pay for it in every incident that waits on one person, every new hire who takes six months to become useful, and every decision re-litigated because nobody wrote down why it was made the first time.

This guide covers the four kinds of documentation an IT team actually needs — runbooks, infrastructure records, disaster recovery plans, and a knowledge base — plus the two things that determine whether any of it survives: where it lives, and how it stays true.

Most documentation efforts fail by treating everything as one undifferentiated pile of pages. But the four kinds of IT documentation are read by different people, under different pressure, for different reasons — and each has a different definition of "good."

• Runbooks are procedures. Someone executes them, step by step, often during an incident. Good means unambiguous.
• Infrastructure records are facts. What exists, where it is, how it connects, who to call about it. Good means current.
• Disaster recovery plans are procedures for the worst day, written on the assumption that normal tools may be unavailable. Good means self-contained.
• The knowledge base is everything else worth keeping: context, decisions, troubleshooting notes, how-it-works explanations. Good means findable.

Keep them separate. A page that is half procedure and half history lesson fails as both: the engineer under pressure cannot find step four, and the engineer seeking context cannot tell which paragraphs are still true. When you know which of the four things you are writing, the format almost chooses itself.

Runbooks earn their keep during incidents, which means they are judged under the worst possible conditions: by a tired person, possibly not the author, with something broken and a clock running. That standard shapes everything about how they should be written — exact commands rather than descriptions of commands, a stated scope so the reader knows within ten seconds whether this is the right document, preconditions checked before step one, verification after the last step, and a rollback path for when the procedure makes things worse.

Which runbooks to write first is an easy call: the ones for things that page you. Restore from backup, certificate renewal, failover, the recovery steps for each service that has actually gone down in the last year. Then the routine-but-rare procedures — the quarterly tasks everyone half-remembers.

The format itself deserves more space than a section here can give it. We wrote a separate piece on writing runbooks people actually use — the structure that survives a 3 a.m. incident, and the review habit that keeps a runbook from quietly rotting into a hazard.

When an engineer asks "what is this server, and can I reboot it?" the answer should not require archaeology. Infrastructure records are the inventory of what you run and the facts attached to each item:

• Systems and services — what each one does, what depends on it, where it runs, and who owns it
• Network basics — address ranges, VLANs, firewall intent (not just rules — what the rules are for), and external connectivity
• Vendors and licensing — support contracts, account numbers, renewal dates, and the phone number that reaches a human
• Access records — who holds admin rights to what, where credentials are vaulted (never the credentials themselves), and which certificates expire when

Two rules keep this useful. First, record ownership and purpose, not just specs — the spec you can rediscover with a scan, but "why does this exist and who screams if it stops" lives only in records. Second, prefer structured records over prose. A service record with named fields — owner, environment, dependencies, renewal date — can be scanned, sorted, and kept current. Ten paragraphs about the same server cannot.

The renewal dates matter more than they look. Expired certificates and lapsed support contracts are among the most preventable outages in IT, and they are prevented by exactly one thing: a record with a date on it that someone is watching.

A DR plan has one design constraint that separates it from every other document you write: it must work when your systems do not. If the recovery plan for your file server lives only on the file server, you do not have a recovery plan; you have irony.

A workable DR plan answers, in order:

1. What are we recovering, and in what order? Dependencies dictate sequence — identity and networking usually come before anything that authenticates against them.
2. Where are the backups, and how do we get at them? Location, access method, and the credentials path — including who can reach the vault if the primary person cannot be reached.
3. Who does what, and who decides? Named roles, contact information that does not depend on the company directory being up, and the escalation point for judgment calls.
4. How do we know we are done?Verification steps per service, so "recovered" means confirmed, not assumed.

Then test it. Not the systems — the document. Hand the plan to someone who did not write it and have them walk it on paper. Every question they have to ask out loud is a defect in the plan, found cheaply. A DR plan that has never been read by a second person has never really been written.

The knowledge base is where documentation efforts most often go to die — not because teams write too little, but because they keep too much. A wiki that mixes current truth with three abandoned migration plans and a 2019 network diagram trains its readers to trust nothing in it. And a knowledge base nobody trusts gets bypassed, which means it stops being updated, which makes it less trustworthy still. That spiral is the whole failure mode.

Three habits keep it alive:

• Write at the moment of resolution.The best documentation is a by-product of real work — the engineer who just spent four hours on a weird DNS issue writes five sentences about it while the pain is fresh. Scheduled "documentation days" produce worse pages at higher cost.
• Archive aggressively. Deleting nothing is how wikis rot. Anything superseded gets archived — retrievable, but out of the search results that people navigate by.
• Date and own every page. A reader deciding whether to trust a page needs two facts: when it was last true, and who to ask. Pages missing either are rumors with formatting.

Good IT documentation is, by definition, a map of your environment — which makes it exactly what an attacker wants and exactly what an auditor will ask about. Two failure modes bracket the problem. Lock documentation down too hard and the on-call engineer cannot reach the runbook during the incident it was written for. Leave it open and your network layout, vendor accounts, and admin ownership list are readable by every account in the company, including the compromised one.

The workable middle: runbooks and general knowledge readable by the whole technical team, infrastructure records scoped to the people who operate them, and anything touching credentials kept in a proper secrets vault with documentation merely pointing to it. Passwords in a wiki page are an incident that has not happened yet. And review who can read what on a schedule — access lists rot exactly the way documents do, just more dangerously.

Teams in regulated industries know this discipline well — it is the same principle that governs healthcare documentation, where who can see a record is as important as what the record says. IT teams supporting those industries inherit the requirement whether they signed up for it or not.

Every team has written documentation. Far fewer have kept it true, because writing is a project and maintenance is a habit — and habits need a system. The one we have seen work is small enough to actually happen:

• Review on use. Whoever executes a runbook or consults a record fixes what they find wrong, right then. Thirty seconds while the discrepancy is in front of you, or thirty minutes for the next person who trusts the error.
• Update on change.Documentation updates ride along with the change that made them necessary — part of the same ticket, same definition of done. Decoupled "we will document it later" means never.
• Sweep on schedule. Once or twice a year, walk the library: archive the dead, flag the doubtful, confirm the owners still work here. An afternoon, not a quarter.

Notice what is absent: heroics. No documentation sprint, no designated scribe, no quarterly push that everyone dreads. Systems that depend on sustained willpower fail; systems that attach small actions to work already happening survive contact with a busy quarter.

If your documentation today is a shared drive and tribal knowledge, do not start with a grand taxonomy. Start with the pain:

1. Write the top three runbooks — the procedures for whatever has actually paged someone in the last six months.
2. Build the service inventory — one structured record per system you run, with owner, purpose, and renewal dates. Ugly and complete beats elegant and partial.
3. Print the DR essentials — or at minimum, get the recovery plan somewhere that survives the outage it describes.
4. Adopt review-on-use — from today, whoever touches a document fixes what they find.

That is a few working days of effort, and it converts the three most expensive kinds of undocumented knowledge into something the whole team holds. The rest of the library can grow the way good documentation always grows: one resolved incident, one onboarded engineer, one "let me write that down" at a time.