Documentation That People Actually Read

S. West

Mar 8

7 min read

Updated: 23 hours ago

Most teams have two documentation problems at once. There are pages nobody reads, and there are questions everybody asks, every week, in a chat channel. The first problem gets all the attention ("we need to write more docs", "we need to clean up the wiki"). The second is the useful one, because it tells you exactly which documentation is missing.

Documentation gets read when it answers a question someone actually has, in the place they look, and when they can trust it's still true. Each of those can be checked. This post starts with finding the questions, then covers the structure that makes pages usable and the practices that keep them true, with a test for each.

Start from the questions people actually ask

The discovery move for documentation is the same as for any product: look at real demand before building anything. Your team's help channel, onboarding notes and support tickets already record it.

A running example (composite). A platform team supports about 120 engineers. Its wiki has around 400 pages. A new engineer takes, on average, nine working days to make their first production deploy. The team exports a month of messages from its help channel: 140 questions. Sorted by topic, the ten most repeated account for about 60% of them: how to get access to the staging cluster, how to add a secret, why the pipeline fails on a missing environment variable, how to roll back, and so on. Six of those ten have a wiki page. Four of the six pages are wrong.

That gives the team a worklist ordered by demand, and it shows that "write more docs" was the wrong instruction. The problem wasn't the number of pages. It was that the pages people needed were missing or untrustworthy.

The test: export one month of questions from your team's help channel (or tickets) and sort them by topic. The ten most repeated questions are your documentation priorities. For each, check whether a page exists, whether it's findable from where people ask, and whether it's correct.

Give each page one job

The old version of this post described four types of documentation without credit. They come from Diátaxis, Daniele Procida's framework for technical documentation, which distinguishes four kinds by what the reader is trying to do:

Type	The reader wants to…	Shaped as	Fails when
Tutorial	Learn, by doing something end to end	Steps that each produce a visible result	A step is broken, or it stops to explain everything
How-to guide	Get a specific task done	Prerequisites, steps, expected outcome	It turns into a tutorial or skips a real-world step
Reference	Look up a fact	Tables and lists, organised for lookup	It's incomplete or out of date
Explanation	Understand why	Prose and diagrams, with trade-offs	It hides the trade-offs or gives instructions

Most pages that nobody finds useful are two types mixed together: a how-to that wanders into architecture history, or a reference page with a tutorial buried in the middle. Each reader has to dig past the part meant for someone else.

In the example: of the six existing pages for the top ten questions, four mixed types. The page on adding a secret started with three paragraphs on why the secrets system was chosen before getting to the command. The team split it into a how-to (five steps) and a short explanation, linked from the how-to's last line.

The test: take your ten most-viewed pages and label each with one of the four types. Any page that needs two labels is a candidate for splitting.

The README is the front door

For a repository, the README decides whether someone can start without asking a person. It needs four things: what the project does (a paragraph), how to get it running, how to run the tests, and where to find more. Writing a README that people actually use goes deeper on the format.

The setup section is the one that rots fastest, because it depends on tool versions and access that change. The only reliable check is running it.

The test: have someone set the project up from the README on a clean machine (or a fresh container), timed, without asking anyone. Every place they get stuck is a missing step. If setup takes more than a handful of commands, the fix is often a script, not more prose.

Keep documentation true: put it where the code changes

Documentation goes stale for one reason: something changes and the docs don't. The practices that work all move documentation closer to the change.

Docs as code. Write the Docs describes "docs as code" as writing documentation with the same tools as code: issue trackers, version control, plain-text markup, code review and automated tests. One benefit it names is that "you can block merging of new features if they don't include documentation."

Update docs in the same change. Google's documentation guide is direct about it: "Change your documentation in the same CL as the code change" (a CL being a change list, Google's term for a pull request). A reviewer can then check the docs the same way they check tests. Many teams add a line to the pull request template: "Docs updated, or not needed because…"

Test the examples. Code samples in documentation are the part most likely to be wrong and the easiest to check automatically. Python's doctest module, for example, "searches for pieces of text that look like interactive Python sessions, and then executes those sessions to verify that they work exactly as shown." A wrong example then fails the build instead of misleading a reader:

def shipping_cost(weight_kg: float, region: str) -> float:
    """Return the shipping cost in the region's currency.

    >>> shipping_cost(2.5, "US")
    12.5
    >>> shipping_cost(2.5, "EU")
    18.75
    """
    rates = {"US": 5.0, "EU": 7.5}  # per kg
    return weight_kg * rates[region]

Other ecosystems have equivalents (Rust's documentation tool runs code examples in documentation as tests, for instance), and API reference generated from an OpenAPI spec or code annotations can't drift from the code it describes.

Delete dead documentation. Google's guide again: "A small set of fresh and accurate docs is better than a large assembly of 'documentation' in various states of disrepair." A page that's wrong does more harm than no page, because people follow it.

The test: look at the last ten merged pull requests that changed behaviour. How many updated the related docs in the same change? If it's few, add the docs line to the pull request template and make it part of review.

Documentation that gets read and stays true. Start from the questions people ask (a month of help-channel questions, sorted). Give each page one job (tutorial, how-to, reference or explanation, from Diátaxis). Keep it true where the code changes (docs in the same pull request, tested examples, delete dead pages). In the composite platform team, the top ten questions were 60% of 140 a month; after six how-tos and fixes, questions fell to 80 and the first deploy for new engineers from nine days to three.

Measure whether it's working

Page views tell you a little. Three other signals tell you more.

Repeated questions. Rerun the help-channel count each month. If the same questions keep coming, either the page is missing, wrong, or can't be found from where people ask. Answering with a link instead of an explanation also trains people to look first.
Failed searches. If your documentation tool reports searches that returned nothing, those are questions with no page.
Time to first contribution. For onboarding docs, the time a new engineer takes to make a first deploy or merged change is the outcome the docs exist to improve.

In the example: after one quarter, the team had written or fixed the pages for the top ten questions (six new how-tos, four corrected), deleted about 150 wiki pages that were obsolete, and added doctests to its internal client library. Help-channel questions fell from 140 to about 80 a month, and the median time to a new engineer's first production deploy fell from nine working days to three.

The test: pick one of the three signals and record it this month. Without a baseline, you won't be able to tell whether any of the documentation work helped.

Why it matters more with AI assistants

Many teams now point an AI assistant at their internal docs so engineers can ask questions in plain language. That makes stale documentation worse, not better. A person reading an outdated page might notice the date or that the screenshot looks old. An assistant that retrieves the same page will repeat its contents confidently. Retrieval-based assistants are only as accurate as what they retrieve, so documentation hygiene is part of the quality of any assistant built on it; RAG architecture covers how those systems retrieve.

Write less, and make what you write checkable

A few habits keep the documentation you do write useful.

Write the shortest page that answers the question. Every sentence is one more that can become wrong. Don't describe what the code says; record what the code can't: why it's structured this way and what constraints aren't obvious. For decisions, an architecture decision record is the right home.
Prefer an example to a paragraph, and make the example runnable.
Show when a page was last verified, not just last edited, and who owns it.
Link, don't copy. A copied paragraph diverges from the original the first time one of them is updated.

For the writing itself, technical writing for people who'd rather write code covers the cold-reader test and the formats that work.

What to do this week

Export a month of questions from your team's help channel and find the ten most repeated. For each, check whether a correct, findable page exists, and write or fix the top three as single-purpose how-to guides. Add a "docs updated, or not needed because…" line to your pull request template. Record one baseline: repeated questions per month, or time to a new engineer's first deploy.

Final takeaway

People read documentation that answers their actual question and that they can trust. So start from the questions they're already asking, give each page one job, and keep docs true by changing them in the same pull request as the code, testing the examples and deleting what's dead. Then measure the questions that keep coming back: they're the clearest sign of what's still missing.

Sources

Procida, D., Diátaxis: a systematic approach to technical documentation authoring; four kinds of documentation (tutorials, how-to guides, technical reference and explanation). https://diataxis.fr/
Write the Docs, "Docs as Code": writing documentation with the same tools as code; "you can block merging of new features if they don't include documentation." https://www.writethedocs.org/guide/docs-as-code/
Google, "Documentation Best Practices" (Google style guides): minimum viable documentation; "Change your documentation in the same CL as the code change"; delete dead documentation. https://google.github.io/styleguide/docguide/best_practices.html
Python Software Foundation, doctest documentation: executes examples in docstrings "to verify that they work exactly as shown." https://docs.python.org/3/library/doctest.html
The rustdoc book, "Documentation tests": "rustdoc supports executing your documentation examples as tests." https://doc.rust-lang.org/rustdoc/write-documentation/documentation-tests.html