What is worth documenting
Not everything, and the wrong prioritisation is why documentation projects stall.
The test is not how often something happens. It is how concentrated the knowledge is and how much it costs when the person holding it is unavailable.
| Priority | Type of process |
|---|---|
| First | Only one person can do it, and it matters |
| Second | Done rarely enough that everyone forgets the details |
| Third | Frequently done by several people, but done differently by each |
| Later | Frequent, routine, everyone already does it the same way |
| Rarely worth it | One-off work that will not recur |
The question that sets priority
What would we struggle to do next week if a specific person were suddenly unavailable? Write that down first. Everything else can wait.
How to actually write it
The single biggest determinant of quality is when you write it.
Write it while someone runs the process, not from memory. Anyone who has done a task fifty times has compressed half of it into instinct. Asked to describe it afterwards, they will genuinely, honestly omit the steps that have become invisible to them, and those are precisely the steps a newcomer gets stuck on.
The efficient version: the person does the task, someone else writes as they go and asks "why did you do that?" whenever a choice is made. Forty minutes of two people produces a better document than four hours of one person trying to recall.
Capture the decisions, not just the actions. "Send the invoice" is an action. "Send the invoice, unless the client is on net-60 terms, in which case wait for the PO" is the actual process. The exceptions are where documents fail, because they are the part that lived only in someone's head.
The structure
The trigger
What starts this. A date, an event, a request arriving, a threshold being crossed.
Documents that begin with step one and never say what prompts step one leave the reader unable to tell whether the process even applies to their situation.
One lineWhat you need before starting
Access, information, approvals, tools. Listed up front.
This exists so nobody discovers at step seven that they needed a permission that takes two days to obtain.
Prevents the mid-process stallThe steps, numbered, in order
One action per step. Where a step involves a choice, state the options and the rule for choosing between them.
Link out rather than explaining a whole other process inline. A document that tries to be complete becomes one nobody finishes reading.
One action per stepWhat good looks like at the end
How the reader knows it worked. The record shows X, the client received Y, the report reconciles.
Without this, people follow the steps and have no way to tell whether the outcome was correct.
A checkable end stateWhat to do when it goes wrong
The two or three most common failures and what to do about each, plus who to ask when it is something else.
Naming a person for the unknown cases is what stops a document being abandoned the first time reality diverges from it.
Name a humanOwner and last reviewed date
At the top, not buried at the bottom. A named person, and the date it was last checked.
A reader can then judge how much to trust it, which is the difference between cautious use and blind use of a document that is a year stale.
At the top
The test that matters
Give it to someone who has never done the task, and let them run it without help.
Sit with them, say nothing, and write down every point where they hesitate, ask a question, or guess. Every one of those is a defect in the document, not in the person.
This is uncomfortable and it is the only reliable way to find the gaps, because the author cannot see them. Assumed knowledge is invisible from the inside by definition.
Fix what they got stuck on the same day. Then the document is finished.
Stopping it going stale
Documentation rots because updating it is treated as a separate task that competes with real work, and it always loses.
Three things that hold it:
A named owner per document, not a team. Shared ownership means nobody notices.
A review date, and a genuinely long interval. Six months for most processes. Long intervals that get honoured beat quarterly reviews that get skipped.
Updating the document is part of changing the process. Not a follow-up task. If someone changes how invoices go out, the change is not finished until the document reflects it.
One more thing worth accepting: a document that is 80% right and clearly dated is far more useful than one that is perfect and undated. People can work with imperfect instructions if they know how much to trust them. What they cannot work with is a confident document that is quietly wrong.
Frequently asked questions
- What processes should we document first?
- The ones that only one person knows how to do and that would hurt if that person were unavailable. Frequency matters less than concentration of knowledge. A monthly task that only one person can perform is a bigger risk than a daily one everybody knows.
- How detailed should a process document be?
- Detailed enough that someone competent but new could follow it without asking. That usually means more detail on decisions and less on obvious mechanics. Where to click matters less than how to decide which option applies.
- Should we use video or written documentation?
- Written for anything people will follow while working, because it can be scanned, searched, and updated in seconds. Video works well for showing an interface once, as a supplement. A video alone is hard to update and impossible to skim.
- Who should write the process document?
- The person who does the work, with a second person watching and asking questions. Written alone, it will skip the steps that have become automatic, and those are exactly the steps a newcomer gets stuck on.
- How do we stop documentation going out of date?
- Put a named owner and a review date on every document, and make updating it part of changing the process rather than a separate task. Documentation rots when it is treated as a project rather than as part of the work.