5.4IT documentation & procedures
The essentials in 30 seconds
- Knowledge kept “in your head” is a risk: absence, departure, forgetting — and the business stalls for lack of someone who knows.
- Three useful forms: procedure (how to do it), runbook (what to do in case of failure), knowledge base (capitalized solutions).
- Good documentation is alive: up to date, findable and actionable — otherwise it misleads.
Running mini-case — Sofiane writes a runbook before his leave
Sofiane, a support technician at a distribution SME in Algiers, is the only one who knows how to restart the file server when it hangs. He is about to go on leave and does not want to leave the team panicking. He applies the section's approach: he writes a runbook “the file server no longer responds”, with precise, ordered steps that a non-expert colleague can understand. He has it tested by another technician: wherever the latter gets stuck, he fixes the doc. He files the runbook somewhere findable, notes the update date, and thus reduces dependence on a single person.
Standalone case for this section: it returns in the course, diagram, script and 48h challenge of section 5.4.
1. Knowledge in your head = a risk
When an operation exists only “in someone's head”, the company depends on that person: absence, departure, forgetting, and everything stalls. Documenting turns personal knowledge into shared knowledge. Sofiane experiences it: the only one who knows how to restart the file server, he prepares the others. It is not paperwork — it is continuity, quality and time saved.
2. Procedures, runbooks, knowledge base
Three useful forms. A procedure describes how to perform an operation (install a workstation, create an account). A runbook is a precise set of steps for a given situation, often a failure (“what to do if server X no longer responds”). The knowledge base capitalizes solutions to problems already encountered, reusable by the whole team and sometimes by users. Sofiane combines the three as needed.
3. Good documentation is alive
Useful documentation is up to date, findable and actionable: clear, tested steps that someone else can follow without you. You update it when reality changes — otherwise it misleads — and you write it for the reader, not for yourself. Documenting as you go costs little; reconstructing afterwards costs a lot. Sofiane systematically notes the update date.
🔎 Concrete example — 🔎 Concrete example — The colleague on leave
Sofiane imagines the file server failure during his absence:
Without a runbook: stall until his return, or risky trial and error
With the runbook “File server no longer responds”:
tested steps → a colleague restores service in 20 minReading: the runbook makes the team autonomous in the face of failure.
Lesson: documenting means not depending on a single person.
Section vocabulary
- Procedure
- Step-by-step description of an operation to perform.
Simple example: Sofiane documents creating a user account.
What it is not: a vague explanation left verbal.
Reflex: procedure = how to do it.
- Runbook
- Precise set of steps for a given situation (often a failure).
Simple example: Sofiane's runbook “file server no longer responds”.
What it is not: improvising when the failure occurs.
Reflex: runbook = what to do in case of failure.
- Knowledge base
- Reusable collection of solutions to problems already encountered.
Simple example: Sofiane records the solutions found there for the team.
What it is not: resolving the same incident ten times from scratch.
Reflex: capitalize solutions.
- Living documentation
- Doc that is up to date, findable and actionable, updated when reality changes.
Simple example: Sofiane dates each doc and fixes it after testing.
What it is not: a never-updated document that misleads.
Reflex: up to date, findable, actionable.
- Bus factor
- Number of people whose absence would stall the business; documentation increases it.
Simple example: Sofiane increases the bus factor by sharing his knowledge.
What it is not: making everything rest on a single person.
Reflex: the more shared the doc, the less you depend.
In practice — In practice — Write a runbook
- Choose a frequent failure you know how to resolve (like Sofiane's file server).
- Write the precise steps, in order, as for a non-expert colleague.
- Have it tested by someone else: if they get stuck, it is the doc that must be fixed.
- File it somewhere findable and note its update date.
Step-by-step script — write a runbook like Sofiane (10 min)
1) Choose a failure you know how to resolve. 2) Write the title as it would be described verbally. 3) List the precise steps, in order, with the exact paths and commands. 4) Add the happy ending: how to check that it is restored. 5) Give it to a non-expert colleague to test. 6) Fix every place where they get stuck, file it and date it.
The magic question to validate a doc: “does someone else succeed without me?” If not, fix it.
Copy-paste template — my runbook
Title: ___ (e.g. “File server no longer responds”)
Symptom observed: ___
1. ___
2. ___
3. ___
Check that it is restored: ___
Where to file it: ___ (findable by the team)
Last update: ___
Rule: up to date · findable · actionable.A failure runbook
Sofiane writes what to do if the file server no longer responds, step by step.
A routine procedure
Sofiane documents installing a standard workstation for the SME.
A knowledge base
Sofiane capitalizes solutions already found so the team doesn't start from scratch.
Living documentation
Sofiane dates and corrects his documents when the configuration changes.
✓ Best practices
- Document as you go: it costs far less than afterwards.
- Write for the reader: clear steps, tested by someone else.
- Keep documentation up to date and findable.
✗ Common pitfalls
- Keeping knowledge in your head.
- Writing documentation never updated: it misleads.
- Documenting for yourself, unreadable to others.
Key takeaways
- Undocumented knowledge is a risk of stalling.
- Procedure (how to do it), runbook (what to do in case of failure), knowledge base (capitalized solutions).
- Good documentation is up to date, findable and actionable.
- Documenting as you go costs less than reconstructing afterwards.
48h challenge — apply it tomorrow
Like Sofiane, write ONE runbook for a failure you know how to resolve: title, symptom, precise ordered steps, and final verification. Have it tested by someone else and fix wherever they get stuck. File it somewhere findable and date it.
- I can explain why undocumented knowledge is a risk.
- I distinguish procedure, runbook and knowledge base.
- I know what makes good documentation: up to date, findable, actionable.
Frequently asked questions
Doesn't documenting waste time?
In the short term a little; in the medium term it saves a lot: fewer re-diagnostics, team autonomy, continuity in case of absence. The real cost is that of knowledge disappearing with the person who held it.
How do I know if a doc is good?
Have someone else execute it: if that person succeeds without asking you, the doc is actionable. Each blockage encountered indicates precisely what to fix.
What is the main value of documenting IT procedures?