Better Documentation

Documentation earns its keep when it removes a question before it is asked. When it fails, the cost is quiet and constant. The work still gets done, but it gets done by interrupting the one person who knows how, by re-discovering the same answer every few weeks, or by guessing and getting it wrong.

The numbers are larger than most teams assume. Recent surveys put the time knowledge workers spend hunting for information at roughly a fifth to a third of the working week, and developers report losing eight or more hours a week to unclear or missing documentation. A single undocumented task held by one person is a standing risk. The day that person is sick, the queue behind their step stops.

There is also a slower failure. A page that was right at launch drifts as the process changes underneath it. People follow it, hit a step that no longer matches reality, and learn to ignore the page entirely. Once a team stops trusting its docs, it stops reading them, and the documentation becomes pure overhead: written, stored, and never used.

Getting it right pays back in onboarding and in flow. Teams with maintained documentation report markedly shorter ramp-up for new joiners and fewer stalled handoffs, because the receiver can act without a meeting. The payoff is measured by readers reaching the correct result on the first try. A document that sits unread delivers none of that value. That is why the mechanics in the next section center on the reader and the task, with coverage following from that focus.

Better documentation rests on two ideas you can apply to any page: write for the person doing the task, and give each page exactly one job.

Write for the doer, action first

Minimalist documentation, the approach John Carroll studied at IBM, starts from how people actually behave. They do not read a manual cover to cover. They want to do the thing, so they skim for the next action. So you lead with the action and the order, keep each step to a real instruction, and move history and rationale below the steps where someone can reach for it once they are stuck. An error is treated as a normal moment the page helps the reader recover from, so the writing spends its space on recovery steps.

One page, one job: the Diataxis four

Daniele Procida's Diataxis framework sorts documentation into four types along two axes, doing versus knowing, and learning versus working:

• Tutorial : a guided lesson that builds a beginner's confidence. The reader is learning, so you choose the path and remove every decision.
• How-to guide : goal-oriented directions for a competent person solving a real problem at work. It assumes baseline knowledge and gets them to a result.
• Reference : accurate, complete facts to look up, free of narrative. Think a settings table or an API field list.
• Explanation : the background and the why, read away from the task to deepen understanding.

The rule that does the work is to keep these separate. A how-to that stops to teach loses the experienced reader; a reference padded with story is slow to scan. Most confusing pages are two or three types fused into one.

Make decisions and recovery explicit

A real task branches. Write the branch as the reader meets it: approved? yes -> send to requester; no -> return to owner with the reason. Then add the recovery line: when a step fails, name the first thing to check. State the prerequisites up front, and state what "done" looks like so the reader knows when to stop.

Keep it from drifting

Give the page a single accountable owner, the one person answerable for it being correct, and a review trigger tied to the work, so changing the process forces changing the page. Where the facts live in a system, generate the page from that single source of truth so re-keying never enters the picture. After this, you can write a page that someone you have never met can follow cold.

Take a support workflow. A request comes in, gets triaged, waits in a queue, is assigned, worked, reviewed, and sent back. The team has one page called "Handling Refund Requests" and new agents keep escalating cases they could close themselves. Reading the page shows why. It opens with three paragraphs on the history of the refund policy, then lists every field in the refund tool, then buries the actual steps near the bottom, with no guidance on the case that needs a manager.

This page is three Diataxis types fused into one: explanation (the policy history), reference (the field list), and a how-to (the steps), all competing for the same opening. Here is how you fix it.

1. Name the reader and the one job. Reader: a support agent. Job: decide and process a single refund request. That makes it a how-to guide.
2. Lead with the action. First line: "To process a refund, open the request in the tool and check the amount against the threshold." The policy history moves to a separate explanation page, linked at the bottom.
3. Write the decision. amount under $200? yes -> approve and refund; no -> route to a manager for sign-off. This single branch is what the agents were escalating around.
4. Add recovery and done. "If the refund button is greyed out, check the order is marked delivered." Done when: "the customer sees a confirmation email and the case is closed."
5. Split the reference. The field-by-field list becomes its own reference page the agent consults only when a field is unclear.

Before, a new agent escalated roughly half their refund cases and a senior agent fielded the questions. After, the how-to fits on one screen, the decision is explicit, and escalations drop to the genuinely hard cases. The history did not vanish; it moved to where someone reads it once, not every time they process a refund.

The traps here are tempting because each one feels like being thorough.

• Describing the system instead of the next action. It is easy to write what a screen contains, because that is visible while you write. The reader needs what to do next. Open every step with a verb the reader performs.
• Documenting only the happy path. The happy path is fast to write and feels complete. Reality branches, so a reader who hits the unhappy case is stranded. Add the common branch and the first recovery check, which is where most real questions come from.
• Treating docs as write-once. A page written and abandoned is worse than no page, because people trust it and then get burned. Tie the page to a review trigger so a process change forces a doc change.
• Over-documenting. A page for every micro-task creates a second maintenance burden and dilutes the pages that matter. Document the tasks that are frequent, risky, or held by one person. Let the obvious ones stay obvious.

Two genuine edge cases deserve a plan. First, the page with no clear owner, often a shared process that crosses two teams. Without an accountable owner it drifts fastest, because everyone assumes someone else will update it. Name one owner even when the work is shared; shared accountability is no accountability. Second, the fast-changing facts, like a config table that shifts weekly. Hand-maintained, it is stale within days. Generate that page from the system of record so the documentation cannot disagree with reality. With single pages handled, the question becomes how to keep many pages alive across a team.

One good page is a craft skill. A documentation set that stays correct across a team is a system, and the system is what keeps the work flowing instead of stalling on tribal knowledge.

The lightweight version of docs-as-code works even for non-engineering teams: keep the page near the work it describes, review a change to it the way you review the work itself, and make updating the doc part of the definition of done for changing the process. When a developer changes code and updates the comment in the same commit, the doc cannot drift; the same coupling works for a procedure and its page. The principle is to update the doc in the same motion as the change, while it is fresh and before a separate task can slip down the queue.

Sustain it with two habits. Assign every page a single accountable owner, applying the one-accountable-owner rule that prevents the orphaned page. And set review triggers tied to real events, a release, a policy change, or a quarterly audit, so the page is checked on a schedule instead of waiting for someone to notice it is wrong. A quarterly pass that retires dead pages matters as much as writing new ones, because a smaller trusted set beats a large stale one.

This practice connects to the rest of the flow. A handoff is only as good as the documentation that travels with it, and the receiver who sets the bar there is the same doer you are writing for here. Treat the documentation set as part of the process flow itself, owned and maintained alongside the work it describes. The durable principle to keep: a page exists to get a reader to the correct result on the first try, and it is alive only as long as someone owns it and something forces it to stay true.