What it costs
Writing While Doing It, Not Afterwards
Writing something down while doing it costs a fraction of writing it afterwards, because afterwards you have to reconstruct what you already had.
What nobody wrote down here, and what it cost
How the staging database is rebuilt
Asked of the same person seven times
Four minutes each, plus the interruption
Which client agreed to the export
Reconstructed from mailbox searches
Twice by people not on the thread
two things nobody wrote down · 10 occasions it cost somebody something
Two things, ten occasions, and nobody billed any of it to anybody.
When a documentation effort needs evidence about where working time actually goes, teams can the Monitask overview before deciding what should be written or automated.
A useful independent point of reference for this part of the process is Crazy Egg.
The same four things, written at the time and written afterwards, with the author's minutes counted
An incident write-up, kept as the incident ran
20 / 168Twenty minutes, spread across the incident in one-line entries
A comparable incident, written up two days later
75 / 126Seventy-five minutes, and three details could not be recovered
A runbook written while doing the thing
30 / 288Thirty minutes, because the author was reading each step anyway
The same runbook if written from memory afterwards
0 / —Estimated at ninety minutes and never started
four documents · 125 minutes written · 582 minutes saved across 39 readings · one with no saving claimed
Four rows, 125 minutes written, 594 minutes saved across 39 readings. The first and third rows cost a third to a half of their afterwards equivalents, and the fourth row is what the afterwards version usually produces. Writing at the time is not a discipline; it is a different and much cheaper task. One team's own quarter.
Two quite different tasks both get called documenting.
Writing something while you are doing it is transcription: the information is in front of you, you are already reading it, and the cost is the typing.
Writing it afterwards is reconstruction: you have to retrieve the details, work out which ones mattered, and discover that two of them are gone. The cost is several times higher and the result is worse.
Why afterwards is so much more expensive
Three multipliers, all of them substantial.
Retrieval. You have to get back into a state you have left, which takes time and is never complete.
Loss. Some details are simply gone — the exact error message, the order you tried things in, the thing you checked and ruled out.
Reluctance. A large reconstruction task scheduled for next week is a task that gets rescheduled, which is the fourth row of the panel above.
The two moments worth catching
Almost all of the cheap writing opportunities are one of two moments.
While following a procedure. Somebody is doing the deploy, or rebuilding the environment, or running the month-end process. They are reading each step as they do it. Typing it into a file as they go adds perhaps a third to the time and produces a runbook.
While something is going wrong. An incident is the single richest documentation moment a team gets: everybody is paying attention, the details are being discovered, and most of what will later be needed is passing through somebody's hands.
The incident case specifically
A running note kept during an incident — one line every fifteen minutes, times included — costs almost nothing and makes the write-up a half-hour edit rather than a two-hour reconstruction.
It also captures the thing reconstruction always loses: what was believed at each point. A write-up assembled afterwards describes the cause; the running note describes the search, which is what makes the next incident shorter.
The objection is that nobody has time during an incident. The entries are one line and take ten seconds. The two hours saved come later, and the person saving them is usually the same person.
What "while doing" writing looks like
Rough. Timestamps, fragments, half-sentences, no structure.
That roughness is a feature rather than a stage to be ashamed of. A file of fragments written at the time contains everything; a polished page written afterwards contains what was remembered. Polishing can happen later, by anybody, and is cheap. Remembering cannot.
What I wrote during it was unreadable. What I wrote two days later was readable and missing the part that mattered, which was the thing I checked at eleven and ruled out.
The structural version
Where this can be built into how work happens, it stops depending on anybody's discipline.
A template at the top of the incident channel with the three lines that need filling. A file alongside the deploy script that the person deploying is expected to touch. A one-line convention after any explanation longer than five minutes.
Each of these attaches writing to an event that was already going to occur, which is the only reliable way to get it done.
Where it does not apply
Reasoning. Why a decision was taken is not usually available at the moment of taking it — the reasons get articulated afterwards, in argument, and that argument is the material.
Anything requiring a view of the whole. Writing while doing produces accurate fragments and never produces an overview, because the person doing has their head in the detail.
Both of those need the afterwards kind of writing, which is why this page is about the cheap half rather than about all of it.
The two moments, side by side
Almost all of the cheap writing in a working week is available at one of two points, and both are recognisable in advance.
- While following a procedure. Somebody is reading each step as they do it. A file open alongside turns the session into a runbook for about a third more time.
- While something is going wrong. An incident is the richest documentation moment a team gets: attention is high, details are being discovered, and most of what will later be needed is passing through somebody's hands.
Both produce rough output and both produce complete output, which is the trade. Polishing can be done later by anybody. Remembering cannot be done later by anybody.
What to try first
The smallest version: next time you follow a procedure that is not written down, keep a file open and paste what you do into it as you go.
At the end you will have an ugly, complete, accurate record that cost you about ten minutes. Somebody — possibly you — can turn it into four clean lines in another ten.
That is the whole method, and it is responsible for more of the documentation that actually exists than every initiative in this collection put together.