Most IT documentation is written to satisfy an audit requirement, not to help the people who need to use it. A confluence page full of screenshots that has not been updated since 2019, a runbook describing a process that no longer matches the current system, a knowledge base article written once and never reviewed: these are documentation failures, not successes. They exist because the requirement was to have documentation, not to have documentation that actually works.
IT documentation has one job: help the person reading it accomplish something they need to accomplish. If it does not do that, it is not good documentation, regardless of how comprehensive or well-formatted it is. This article covers what to document, how to write it so people actually read it, and how to keep it current once it exists.
Documentation That Earns Its Place
The most useful IT documentation falls into three categories: reference documentation, procedural documentation, and decision documentation. Each category serves a different purpose and reaches a different audience, and trying to serve all three with a single document format is a common mistake that produces documentation nobody wants to use.
Reference documentation describes what a system is and how it is configured. This type of information belongs in a CMDB or asset register, not in a long-form document. Nobody reads a five-page document to find out what a server's IP address is. They look in the asset register. Long-form documentation should be reserved for procedures and decisions that require context to understand.
Procedural documentation is the most read and most needed. Step-by-step instructions for tasks that people perform infrequently enough that they cannot do them from memory: how to provision a new user account, how to restore from backup, how to diagnose a network connectivity problem. The key to good procedural documentation is that it must work for the person reading it at the moment they need it, which means it must be accurate, complete, and free of ambiguity about what to do next.
Decision documentation captures why a particular technical choice was made. When a future team member questions why a system was configured a certain way, good decision documentation explains the context and constraints that led to that choice. Without it, important decisions get reversed or recreated from scratch simply because nobody remembers why they were made.
The Problem With Out-of-Date Documentation
Documentation that is not maintained is worse than no documentation at all. No documentation at least creates uncertainty that prompts investigation. Documentation that looks authoritative but is wrong leads people confidently down the wrong path, wasting time and potentially causing incidents. The documentation maintenance problem is not a technology problem; it is a process and culture problem.
The solution is to treat documentation as part of the task it describes, not as a separate deliverable. If the runbook for restoring a backup is separate from the restore procedure itself, the runbook will drift. If the restore procedure is documented as part of the task ticket, and the ticket is closed only when the documentation is updated, the documentation stays current.
Building an IT support runbook library is most effective when each runbook is treated as a living document. A runbook created during an incident and immediately reviewed is better than no runbook at all, but only if it gets updated when the system changes. Reviewing runbooks during regular maintenance windows helps prevent documentation decay before it causes problems during an actual incident.
Writing for the Reader, Not the Author
Most IT documentation is written from the perspective of the person who built the system, not the person who needs to use it. This creates documentation that assumes context the reader does not have. The fix is to write each document from the perspective of the person reading it: what do they need to know before they start, what steps do they take, what can go wrong, and what do they do about it.
Use numbered lists for sequential steps. Use bullet points for parallel options. Do not use bold or italics for decoration; use them to mark critical warnings or optional steps. Every document should have a clear single purpose. If you find yourself writing "by the way, this also applies to..." you probably have two documents that should be separate.
Screenshots date badly and rarely survive a software update. Describe what the user should see rather than showing them a picture of it. If you must include screenshots, include them as secondary reference and make the text description the primary instruction. A screenshot of a dialog box in version 3.2 of a application is useless when the application reaches version 5.0, but a text description of what the dialog does remains relevant regardless of version.
Where to Put Your Documentation
The best place for IT documentation is wherever your team actually looks for it. If they use Notion, put it in Notion. If they use Confluence, put it there. If they use a shared folder with markdown files, put it there. The tool matters less than the habit of using it.
What matters more than the tool is having a single authoritative source. When documentation exists in multiple places, such as a shared drive, an email thread, and a sticky note on a monitor, the versions diverge and nobody knows which one is current. Pick one system, put everything in it, and delete the duplicates.
For smaller IT teams, a simple folder structure with markdown files works well. For teams that need searchability and cross-linking, a dedicated wiki like BookStack or Notion is more appropriate. The key is choosing something your team will actually use, not the most feature-rich option on the market.
Documentation for Onboarding and Offboarding
Documentation becomes most critical when someone joins or leaves. A realistic IT onboarding process depends heavily on documentation being available before the new person starts. Without it, their first weeks are spent tracking down information that should be readily available, slowing their productivity and creating extra work for the rest of the team.
When someone leaves, if they are the only person who knows how a particular system works, that is a business continuity risk, not just a documentation problem. Good documentation means that when someone leaves, their knowledge leaves with them, not the ability of the business to continue operating.
Offboarding documentation should include access credentials stored securely, system-specific knowledge not captured anywhere else, contacts for vendors and third-party support, and any outstanding issues or known problems with each system. This information should be captured before the offboarding conversation, not during or after it.
The Cost of Documentation Debt
When documentation is neglected over time, it becomes a liability rather than an asset. Teams develop workarounds for missing or incorrect documentation, which creates informal processes that exist only in people's heads. When those people leave, the workarounds leave with them. New team members cannot get up to speed quickly because the documentation they find is wrong or missing. Incident response is slower because nobody can quickly find the relevant system documentation, so they have to figure out the system from scratch while an incident is active.
This cost is invisible until it is suddenly very visible, usually during a crisis. The investment in maintaining documentation is small relative to the cost of not having it when you need it most. Treat documentation maintenance as a cost of doing business, not as an optional extra when there is time.
Documentation debt accumulates slowly but compounds quickly. A single missed documentation update seems harmless, but after six months of changes without documentation updates, the gap becomes significant. After a year, the documentation may be completely misleading rather than merely incomplete.
Standard Operating Procedures for IT
Beyond reference documentation and runbooks, consider building Standard Operating Procedures for the most common IT processes. Each SOP should be written as a step-by-step guide, not a policy document or a set of principles. The person reading the SOP at 3am during an incident should be able to follow the steps without interpretation.
Key SOPs every IT team should have include onboarding a new employee with laptop setup, account creation, required software, and access provisioning, offboarding a departing employee with access revocation, device recovery, and data ownership transfer, responding to a security incident with containment, communication, and escalation steps, and restoring from backup with verification steps, timeline expectations, and required sign-off.
Each SOP should have a version number, a last-reviewed date, and a named owner responsible for keeping it current. Without these metadata elements, there is no way to know whether a document is still accurate or has been superseded by a newer version.
How to Structure a Runbook
A runbook is a specific type of documentation for operational procedures. It explains how to diagnose a problem, how to fix a known issue, or how to perform a specific operational task. Building an effective IT support runbook library starts with identifying the procedures your team uses most often during incidents and service interruptions.
A good runbook has a clear title that describes the problem it solves, a summary of symptoms that indicate this runbook is relevant, a step-by-step procedure with specific commands and expected outputs, a section on what to do if the standard procedure does not resolve the issue, and contact information for escalation if needed.
Write runbooks for the most common incidents your team handles, not for every possible failure mode. If a failure mode has no documented runbook, the first time it occurs, document it as you fix it. Creating runbooks retrospectively from a real incident ensures they capture the actual steps taken rather than theoretical steps that seemed reasonable at the time of writing.
Measuring Whether Documentation Is Working
You can tell if your documentation is working by whether people ask the same questions repeatedly. If the same procedural question keeps coming up in chat or in support tickets, the documentation for that procedure either does not exist or does not work. Track repeat questions as a documentation quality signal rather than treating them as annoying interruptions.
Another measure is how long it takes a new team member to become productive. If a new hire needs three months to stop asking basic questions about systems and processes, that is a documentation gap. If they are productive within three weeks, your documentation is probably working. The specific timeframe varies depending on the complexity of your environment, but the principle remains the same.
Documentation quality also shows up in incident resolution times. When responders can quickly find the relevant runbook and follow it, incidents get resolved faster. When they have to figure out the system from scratch while managing a live incident, resolution takes longer and the risk of mistakes increases.
What to Document When You Are Starting From Nothing
If you are starting with no documentation at all, begin with the systems that would cause the most business disruption if they failed. Document those first, then work outward to less critical systems. This prioritisation ensures that the most important documentation gets created first, when energy and motivation are highest.
When documenting a system, start with the information you would need to rebuild it from scratch if it were completely destroyed. That exercise reveals what is actually important versus what seemed important when the documentation was originally written years ago.
For each system, document the purpose it serves, the dependencies it has and that depend on it, the access credentials and where they are stored, the backup and recovery procedure, and the contact details for the person or team responsible for maintaining it.
Common Documentation Mistakes to Avoid
The most common documentation mistake is writing documentation as a one-time project rather than an ongoing commitment. Documentation created during a documentation sprint and never touched again will be out of date within weeks. Sustainable documentation practices built into daily work are more effective than periodic documentation drives.
Another mistake is over-documenting. Not every server needs a thirty-page manual. Document the standard configuration once, and document only the deviations from that standard for individual systems. Over-documentation creates noise that makes important information harder to find.
Under-documenting critical procedures is the opposite problem but equally damaging. The procedures that are performed most infrequently, such as disaster recovery or major incident response, are the ones most likely to be forgotten when they are needed. These deserve the most careful documentation, not the least.
Making Documentation Part of Your IT Culture
Documentation culture comes from leadership behaviour, not documentation policies. If the team lead consistently closes tickets without updating documentation, the team learns that documentation is optional. If the team lead treats documentation updates as non-negotiable parts of every task, the team learns that documentation is part of the job.
Recognise and reward good documentation behaviour. When someone takes the time to document a procedure thoroughly, or updates documentation after a system change, acknowledge that contribution. Documentation work is often invisible, so making it visible helps reinforce the behaviour you want to see.
Include documentation review in your regular maintenance schedule. Monthly or quarterly reviews of key documentation catch drift before it becomes dangerous. A quick review of whether the documented steps still match the actual system takes minutes but prevents confusion during incidents.
Where to Start
If your documentation needs work, pick one system that would cause significant business disruption if it failed and document it properly. Get the structure right: clear purpose, step-by-step instructions, what to do when things go wrong, and who to contact for escalation. Once you have one good document, use it as a template for the next one.
The hardest part is starting. A single well-maintained runbook is more useful than a hundred documents that nobody trusts because they are out of date. Build documentation habits into your daily work rather than treating it as a separate project, and the documentation will take care of itself.
If you are reviewing your current documentation and finding significant gaps, or if you want help building a documentation framework for your IT environment, you can get in touch to discuss what would be most useful for your specific situation.