Good docs are a 10x engineering multiplier

The standard framing for documentation is that it helps the person reading it: the new hire, the junior engineer, the colleague working in an unfamiliar part of the codebase. This is true, but it dramatically undervalues the benefit by focusing on the wrong side of the equation.

The much larger benefit is to the people who stop getting interrupted.

The interruption cost

A senior engineer working on a complex problem needs sustained concentration. Research on context switching consistently shows that an interruption, even a brief one, costs far more than the duration of the interruption itself. Gloria Mark's work puts the recovery time at roughly 25 minutes to return to the same level of focus after a disruption.

A senior engineer who gets interrupted ten times a day by questions that would be answered by good documentation loses not just the ten minutes of answering but roughly four hours of productive focus to the recovery cost. That's half the working day consumed by the absence of docs, and the engineer often doesn't recognise what's happening because each individual interruption feels small and manageable.

The questions themselves are entirely reasonable. "Why is the auth service structured this way?" "Where do I find the deployment guide?" "What was the reasoning behind using this queue instead of a database?" "How does the data pipeline handle failed records?" Every one of these questions has an answer, and in a team without docs, the answer lives in a senior engineer's head and can only be accessed by interrupting them.

The multiplication effect

Good documentation creates a multiplication effect that grows with team size.

In a five-person team, interruptions are manageable because the team is small and the context is shared. In a twenty-person team with five senior engineers and fifteen people who regularly need context from them, the interruption load scales non-linearly. Each senior engineer is now a bottleneck for three or four people's questions, and the aggregate cost to the senior engineers' productivity is substantial.

Documentation breaks this bottleneck by making the senior engineers' knowledge available without requiring their attention. The junior engineer reads the architecture doc instead of asking. The new hire follows the onboarding guide instead of requesting a walkthrough. The colleague working in an unfamiliar area of the codebase reads the decision log instead of scheduling a meeting.

Each question redirected from a person to a document saves the asker's wait time and the answerer's interruption cost. At ten questions per day across the team, the saving is two to four hours of senior engineering time, which is the equivalent of having an additional senior engineer whose sole contribution is answering questions by proxy.

Who benefits most

The people who benefit most from good documentation are typically the most senior and most valuable engineers on the team, the ones whose time is most expensive and whose concentration is most critical. These are the same people who carry the largest documentation burden when docs are created manually, which creates a particularly wasteful dynamic: the people whose focus is most valuable are the ones most frequently interrupted, and the solution (writing docs) also falls on them, consuming more of the focus it's supposed to protect.

Self-writing documentation breaks this cycle by generating docs from the senior engineer's existing output (their PR descriptions, their Slack explanations, their meeting contributions) without requiring additional work from them. The knowledge they're already sharing in context-specific ways is captured and structured so it's findable by anyone, at any time, without interrupting its source.

Frequently asked questions

How do we measure the interruption cost? Track the number of questions senior engineers receive via Slack DMs and in-person requests for one week. Multiply by 25 minutes (the average recovery cost per interruption) to get the total focus time lost. Most teams find the number is much higher than they assumed.

Won't junior engineers just not read the docs? If the docs are current, well-organised, and searchable, adoption is typically high because the alternative (waiting for a senior engineer to respond) is slower. If the docs are stale and untrustworthy, engineers won't read them regardless. The quality of the docs determines the adoption.

Does this justify the cost of a documentation tool? At senior engineering salaries, recovering even two hours per week of focus time across a small team typically exceeds the cost of any documentation tool on the market. The ROI calculation is almost always positive, and the benefit grows with team size.

Related reading: Why engineering docs matter, The cost of writing engineering docs, The hidden cost of tribal knowledge. Related pages: Self-writing docs, For engineering teams.