Technical writing fundamentals

Docs-as-code means the documentation is plain text in a version-control repository, reviewed through pull requests, built by a pipeline and deployed like software. What you get is not primarily convenience. It is that documentation becomes visible to the same mechanisms that already keep code honest: a change to a page has an author, a diff, a reviewer and a date, and a change to the code can be blocked until the page changes with it. The cost is that contribution now requires a git workflow, which excludes some of the people who have the most to say - support engineers, solutions architects, anyone whose day is not spent in a terminal. Teams that adopt it and then wonder why contributions dropped have usually not noticed that they raised the price of writing a paragraph.

A tutorial teaches a skill to someone who does not have one yet, so it is narrated, sequenced, and offers no choices - every decision is made for the reader so that the exercise finishes. Its success criterion is completion. A how-to guide serves someone who already has the skill and now has a goal, so it is titled after the goal, assumes context, and may reasonably say "configure whichever storage backend you use". Its success criterion is that the goal is reached. The confusion matters because a tutorial that starts offering alternatives stops being finishable, and a how-to guide that starts teaching fundamentals wastes the time of someone who is mid-task.

Single-sourcing is writing a piece of content once and rendering it into every place it is needed, rather than copying it. In practice that is an include or transclusion mechanism: a prerequisites block, an authentication snippet or a warning about a destructive flag lives in one file and is pulled into the six pages that need it. The benefit is that correcting it once corrects it everywhere, which is the only reliable defence against a set of pages that disagree. The cost is that an included fragment is written without knowing its surroundings, so it drifts towards a generic tone and cannot refer to the step before it.

Progressive disclosure means showing a reader only what they need to act now, and putting the rest one link or one collapsed section away. A quickstart shows the three required parameters and links the reference table with the other twenty-one. It works because the cost of a page is not its length but the number of decisions it forces, and a reader who has to evaluate options they do not understand yet stalls. The failure mode is using it to hide something load-bearing: a prerequisite or a data-loss warning behind a collapsed heading is not disclosed progressively, it is disclosed too late.

Both exist to make fifty contributors sound like one, and they do different jobs.

artefact            governs                  example entry                        enforced by
------------------  -----------------------  -----------------------------------  ------------------
Terminology list    which word names a       "Use workspace, never tenant or      text linter,
                    thing                    org"                                 review

Style guide         how sentences are        "Procedures use numbered steps       review, templates
                    built                    and the imperative"

Voice statement     register and stance      "Direct, second person, no           editor judgement
                                             exclamation marks"

Formatting rules    page mechanics           "One H1, sentence-case headings,     markdown linter
                                             no bold in body text"

Content templates   what a page must         a reference page carries a           pull-request
                    contain                  parameters table                     template

A terminology list is the highest-value document of the five and the cheapest to maintain, because inconsistent naming is the defect readers notice first: if the API calls it a workspace, the console labels it an org and the docs alternate, readers conclude these are three different objects and file a ticket asking how they relate.

The style guide is worth writing only for the rules you will actually enforce. A forty-page guide nobody reads produces no consistency and a great deal of guilt, whereas a one-page guide with eight rules and a linter produces most of the available benefit. Anything you cannot state as a checkable rule belongs in the voice statement, where it is honestly labelled as judgement.

The row that teams skip is templates, and it is the one that changes behaviour without any review effort. A contributor given an empty file writes whatever shape they last read; a contributor given a page with a Prerequisites heading already in it fills it in, which converts the most common blocking review comment into a structural default.

Topic-based authoring treats each self-contained unit of content as the authoring object rather than the page or the chapter. A topic answers one question or describes one procedure, carries no dependence on what came before it, and can be assembled into different outputs - a web page, a printed manual, an in-product help panel. The discipline it imposes is useful even without tooling: if a topic cannot be understood on its own, it will not survive being found through search, which is how most readers arrive. The cost is a set of topics with no narrative thread, so someone still has to build and maintain the assembly that gives them an order.

It is the decision about what the units of content are, how they are grouped, how a reader moves between them, and what each page is allowed to contain. That covers the navigation tree, the naming of sections, the boundary rules that keep reference out of tutorials, and the entry points a reader lands on. It is architecture in the real sense because it is expensive to change later: URLs get linked, search engines index them, and support macros point at them, so a restructure means redirects and a period of broken bookmarks. Getting the top two levels roughly right early is worth more than perfecting any single page.

A technical writer's output is content: they interview engineers, learn the system, decide what a reader needs and write it. A documentation engineer's output is the machinery: the site generator, the CI checks, the reference generation from a spec, the link checker, the versioning scheme, the search index. Small teams combine the two roles and the combination is common enough that job titles are unreliable. The distinction matters in an interview because the two are scored differently - one round probes whether you can restructure a bloated page, the other probes whether you can make a broken build fail loudly, and turning up prepared for only one of them is a common mistake.

Because proximity is the only thing that makes a documentation change part of a code change. In the same repository the author who alters a flag sees the page that documents it in their editor, the reviewer sees both diffs in one pull request, and a CI rule can require that a change under src/api touches something under docs/. Split them and documentation becomes a separate task with a separate queue, which is where it starves. The counter-argument is real: a monolithic docs site covering twelve services cannot live in all twelve repositories, so large organisations end up with a central site that pulls fragments from service repositories, and then have to keep that assembly working.

The pipeline is where documentation quality stops being a matter of attention.

flowchart TD
  PR[Pull request opened] --> L[Lint markdown<br/>headings, terminology]
  L --> S[Validate spec<br/>and regenerate reference]
  S --> B[Build site]
  B --> K[Check links<br/>internal and external]
  K --> P[Deploy preview URL]
  P --> R[Human review<br/>reads the preview]

Read the order rather than the boxes. Everything mechanical runs before a human is asked to look, so the reviewer never spends a comment on a heading level or a broken relative link. That is the whole design goal: a review comment is the most expensive way to enforce a rule a script could enforce, and it is also the one that makes a contributor feel judged.

The preview deploy is the step teams add last and value most. Markdown source diffs hide the defects that matter - a table that does not render, a code fence with the wrong language, a diagram that failed to parse and degraded into a block of source. None of those are visible in a diff and all of them are obvious on a rendered page.

External link checking is the one step worth making non-blocking. Third-party sites go down for reasons unconnected to your pull request, and a docs build that fails because someone else's blog is having a bad afternoon trains people to merge past red checks. Run it on a schedule against the main branch instead, and file an issue rather than failing a build.

It turns a directory of Markdown and a set of templates into pre-rendered HTML at build time, so the served page needs no application server and no database. The consequences are what you are buying: pages are fast and cheap to host, the whole site can be deployed atomically so there is no half-updated state, and the build is a natural place to hang checks - a broken link or an unresolved include can fail the build instead of reaching a reader. What you give up is anything that needs to be per-request. Personalisation, gated content and search over private material all need something else, which is why search is usually a client-side index built at the same time as the pages.

Frontmatter is the metadata block at the top of a Markdown file, and what you put there determines what the build can do without a human.

---
title: Rotate a service credential
description: Replace a live credential without dropping in-flight requests.
mode: how-to                 # drives navigation grouping and page template
appliesTo: ["3.2", "3.3"]    # version selector; absent means all versions
owner: platform-identity     # a team, never a person who may leave
reviewed: 2026-07-14         # drives the staleness report, not "last edited"
redirectFrom:
  - /docs/credentials/rotation   # the old URL, kept forever
---

The two fields that earn their place are owner and reviewed. Ownership by team rather than individual is what makes a staleness report actionable - a report addressed to nobody is a dashboard, a report addressed to a team is a backlog item. And reviewed has to be set deliberately rather than derived from the commit date, because a typo fix would otherwise mark a page as freshly verified when nobody checked whether it is still true.

redirectFrom is the field people add after their first restructure. URLs are the public interface of a docs site: they are in support macros, in error messages, in other people's blog posts. Moving a page without leaving the old path resolvable breaks all of those silently, and search engines take months to recover.

The mode field is worth having if your information architecture distinguishes tutorials from reference, because it lets the build enforce the boundary - a page declaring itself reference can be required to carry a parameters table, and a tutorial can be checked for the phrase patterns that indicate it has started offering options.

Three mechanisms, in order of value. First, never move a URL without leaving a redirect from the old path, and keep that redirect permanently rather than for a release. Second, check internal links at build time and fail on a broken one, which is cheap because everything needed is in the repository. Third, check external links on a schedule against the main branch and file issues, because failing a pull request on somebody else's outage teaches people to ignore red builds. Beyond that, prefer linking a page over linking an anchor within it, and avoid deep-linking third-party documentation whose structure you do not control.

The usual answer is a directory or branch per supported version, with a version selector on the page and one version marked current for search engines through canonical tags. That is straightforward and the difficulty is entirely in the maintenance: a correction now has to be backported to every supported version, and the older copies rot quietly because nobody reads them until the one customer still on that release does. Two things reduce the pain. Keep the number of published versions small and state the support window explicitly. And version only what actually changes - conceptual explanation is usually stable, so duplicating it across five versions buys nothing but five places to fix a typo.

They go stale invisibly. A screenshot is opaque to every check you own: no linter reads it, no test fails when the button it shows is renamed, and it survives a redesign that invalidated it. It is also the most expensive asset to update, because reproducing the exact state takes longer than writing the sentence it replaced. So the working rule is to use a screenshot only when the reader needs to recognise something visually - where a control physically sits, what a chart looks like when healthy - and to use text for anything nameable. Where they are unavoidable, generate them from a UI test so they refresh with the build rather than by hand.

The framework separates documentation by what the reader is doing, not by subject.

                    ACTION                          COGNITION
                    the reader is doing             the reader is understanding

AT STUDY            Tutorial                        Explanation
acquiring skill     "teach me to do this at all"    "why is it built like this"
                    excludes: choices,              excludes: steps to follow
                    alternatives, caveats

AT WORK             How-to guide                    Reference
applying skill      "get me to this goal"           "what is the third enum value"
                    excludes: teaching of           excludes: narrative,
                    fundamentals                    rationale, history

The two axes are the useful part: action against cognition, and study time against work time. They are what make the four modes derivable rather than arbitrary, and they are why the framework survives contact with a real docs set where someone always wants a fifth category.

The boundary teams get wrong most often is reference against explanation, because both answer "how does this work". The test is whether the reader is mid-task. Design rationale on a reference page forces the person debugging at 2am to step over three paragraphs of history to reach a parameter default, and that is the concrete harm - not a taxonomy violation.

The excludes lines are where the framework does its work. Each mode is defined as much by what it excludes as by what it holds, and the exclusions are the instructions that are hard to follow: taking a true and important production caveat out of a tutorial feels like removing value, and it is the change that makes the tutorial finishable.

Diataxis is one answer rather than the answer. It suits products with a genuine learning curve and a large surface; a single-endpoint internal service does not need four sections, and imposing them produces four thin pages instead of one good one.

The question a contributor asks most often, and a decision tree answers it faster than a framework document.

flowchart TD
  P[New paragraph to place] --> A{Does it tell the reader to do something}
  A -->|Yes| B{Would a newcomer follow it start to finish}
  A -->|No| C{Does the reader need it mid-task}
  B -->|Yes| T[Tutorial step]
  B -->|No| H[How-to guide]
  C -->|Yes| F[Reference entry]
  C -->|No| E[Explanation]

Follow the left branch first, because "does it contain an instruction" is the one question a contributor can answer about their own paragraph without knowing the information architecture at all. Most misplacements are instructions that have been dropped into an explanation page, where readers dutifully follow them even though nobody tests them.

The right branch is the harder one and the phrasing is deliberate: not "is it conceptual" but "does the reader need it while working". A sentence explaining that IDs are ULIDs and therefore sort by creation time is conceptual and belongs in reference, because someone is looking at an ID right now and wondering.

What the tree cannot decide is whether the paragraph should exist. A contributor who has just debugged something painful often wants to write the story of the debugging, and the answer is frequently that two sentences of it belong in reference as an error description and the rest belongs in a postmortem.

Because it mirrors your architecture and mirrors nothing about why the reader arrived. A page per service is discoverable only by someone who already knows which service owns the behaviour they are asking about, which is exactly the knowledge a reader lacks. It also guarantees that any task crossing two services has no home, so it either goes missing or gets written twice and diverges. The architecture-shaped structure is not useless - it is the right shape for internal reference read by the teams who own those services - but it is the wrong shape for the front door, where headings should name what a reader is trying to do.

The reader stops. A tutorial is for someone with no model of the system, so they have no basis for choosing between two options and no way to tell whether the choice will matter later. Offering one converts a sequence they can follow into a decision they cannot make, and the honest outcome is that they pick arbitrarily, hit an error three steps later, and cannot tell whether they chose wrongly or broke something else. This is why the correct edit to a tutorial is usually a deletion: the production caveat, the alternative backend and the note about Windows paths all come out, into a how-to guide the reader will find once they know what they are doing.

Do it by reader intent, and let the split be visible in the outcome rather than in the section names.

Before
  getting-started.md   4,100 words
    install
    first successful call
    all 24 environment variables      <- lookup material, never read in order
    configuring TLS in production      <- a goal, not a first step
    why the client pools connections   <- interesting, blocks the newcomer
    troubleshooting: 9 error cases     <- lookup material

After
  tutorial/first-call.md          620 words, one path, no options
  how-to/configure-tls.md         340 words, titled after the goal
  reference/environment.md        table only, alphabetical
  reference/errors.md             one row per error, cause and action
  explanation/connection-pool.md  340 words, no steps

The word count is the least interesting change. What matters is that the tutorial went from unfinishable to finishable by losing content that was accurate, and that the twenty-four variables became a table that can be scanned instead of prose that had to be read.

Two things must happen at the same time or the split makes the docs worse. Every old anchor needs a redirect, because a four-thousand-word page has accumulated deep links from support tickets and Stack Overflow answers. And the new pages need explicit sibling links - the tutorial pointing at the TLS guide, each error row pointing at the how-to that fixes it - or a reader who used to scroll now has to search.

The judgement call is the troubleshooting section. Nine error cases as reference rows is right when each has a distinct cause and action; if three of them are the same misconfiguration seen from different angles, the honest outcome is one how-to guide named after the misconfiguration and three reference rows pointing at it.

When both pages are read by someone about to take the action. A data-loss warning belongs in the how-to guide that walks through the operation and in the reference entry for the flag, because those readers arrive by different routes and neither will read the other page. Single-sourcing the warning as an include gives you the duplication without the divergence, which is the version to prefer. What is not correct is duplicating explanation - two pages narrating why the system behaves this way will drift, and the drift is invisible because both remain plausible. Duplicate short imperatives; link long reasoning.

Orientation, in the first two lines, because that reader has no idea where they are. Concretely: a title that names the task rather than the topic, an opening sentence that says who the page is for and what it assumes, a visible statement of which product version it describes, and a link to the sibling page in the mode they may actually have wanted. Most readers never see your navigation tree, so a structure that only makes sense from the top level is a structure most of your audience never experiences. The practical test is to open a random deep page cold and ask whether you could tell what it assumes.

Because it is a second copy of the interface, held in a different file, edited by a different person at a different time, with nothing connecting the two. No test fails when a field becomes optional and no build breaks when a status code is added, so the page stays wrong until a reader reports it. Framing it as a discipline problem is the mistake: teams with excellent discipline still drift, because the mechanism that would catch the error does not exist. The fix is structural rather than cultural, which means deriving the mechanical part of the reference from one source and putting something in CI that fails when the source and the service disagree.

It expresses shape well and semantics badly.

paths:
  /v1/payments/{id}/capture:
    post:
      summary: Capture an authorised payment
      description: >
        Call only after /v1/payments returns status=authorised. Repeating the
        call with the same Idempotency-Key returns the original result.
      parameters:
        - name: Idempotency-Key
          in: header
          required: false      # required in practice; the schema cannot say why
          schema: { type: string, format: uuid }
      responses:
        "409":
          description: >
            Payment is not in the authorised state. Not retryable - refetch the
            payment and branch on status.

Everything outside the description blocks is derivable and therefore safe to generate: the path, the method, the header name, its type, the set of status codes. That half of a reference page never needs to be written by a human again.

The description blocks are the half that decides whether the endpoint is usable. A schema can say a response is a 409; only prose can say that this 409 means a state conflict and is not worth retrying, while the 409 on a sibling endpoint means a duplicate business key and behaves differently. Sequencing is the same story - nothing in a specification format expresses "call this endpoint first", so it lives in a sentence or it lives nowhere.

The required: false line is the honest awkwardness. The header is optional to the protocol and mandatory to anyone who does not want double captures, and the gap between those two facts is exactly the space prose has to fill.

A schema validator tells you the document is well-formed; a linter tells you it is documented.

rule                              fails when                      why it matters
--------------------------------  ------------------------------  ------------------------
operation has a description       only summary is set             a one-line summary
                                                                  cannot carry sequencing

every response documented         a 4xx exists with no text       undocumented errors
                                                                  become support tickets

examples validate against         the example predates a          a wrong example is
the schema                        field rename                    worse than none

no placeholder text               "TODO" or "Description"         generation makes
                                  survives into the build         placeholders look official

operation IDs are stable          an ID silently changes          generated client method
                                                                  names break

deprecated flag is set            a sunset endpoint still         the commonest silent
                                  renders as current              staleness

The last row is the one that repays the setup cost. A generated reference is complete by construction, so the reader has no way to tell that an endpoint has been discouraged for two quarters - it renders identically to the endpoint you want them to use. Silence in a generated artefact is invisible in a way that silence in a hand-written page is not.

The examples rule catches the defect that survives every other check. An example payload is not exercised by the service, so a renamed field leaves it plausible and wrong, and readers copy examples far more often than they read schemas.

Where linting cannot help is judgement: no rule can distinguish a description that explains the endpoint from one that restates its name. "Captures a payment" passes every check above and tells the reader nothing, which is why the review of the spec diff stays a human job.

By writing each one as a decision rather than as a code, in a fixed entry shape.

### 409 payment_not_authorised

The payment is no longer in a state that permits capture, usually because it
expired or was already captured.

- **Retryable** no. Retrying returns the same error indefinitely.
- **Do this** refetch the payment and branch on `status`.

### 409 duplicate_reference

The `reference` you supplied already exists on another payment in this workspace.

- **Retryable** no, not with the same reference.
- **Do this** compare the returned payment id with your own record. If it is
  yours, treat the call as successful. If it is not, choose a new reference.

### 503 upstream_unavailable

The card processor could not be reached.

- **Retryable** yes, with jitter and an `Idempotency-Key`.
- **Do this** retry, and be aware the capture may already have succeeded
  upstream. Reconcile on `status` before charging again.

Every entry answers the same three questions in the same order, and the retry line is where the value sits. A reader hitting an error at 2am has exactly one decision to make - retry, branch or stop - and a page that lists codes and messages leaves them inferring it from the wording, which is how a non-retryable error ends up inside a retry loop.

The two 409 entries prove the machine-readable definition is not enough. Same status, same endpoint family, opposite correct behaviour, and nothing but a sentence distinguishes them. A generated reference derived from the specification alone would render them as one row.

The 503 entry admits something uncomfortable: the operation may have succeeded despite the error the caller saw. Saying so is the sentence that prevents a double charge, because a client author who does not know it retries blindly. Documentation that only describes the happy semantics of failures is worse than none, since it produces confident wrong handling.

In three places. If the specification is a hand-maintained file beside the code, you renamed the second source of truth rather than removing it, and it drifts behind a facade of automation. If the specification comes from annotations, the annotations can be wrong in ways the compiler tolerates - a documented type that no longer matches the serialiser, an example left over from a rename. And because a generated page is complete by construction, omissions are invisible: a soft-deprecated endpoint still renders as first-class, and an internal route that gained a public annotation by copy-paste appears on your public site. The defences are validating real payloads against the spec in integration tests, and reviewing the rendered diff rather than only the source diff.

Four things, and the order they appear in matters more than the wording. First, the reference entry for the old thing is marked deprecated at the top, before any description, so a reader who scans does not miss it. Second, it states what to use instead, with a link, in the same sentence - a deprecation notice without a destination is an obstacle rather than guidance. Third, a dated statement of when it stops working, or an explicit statement that no date is set, because "will be removed in a future release" is the phrasing that makes readers ignore deprecation notices. Fourth, a migration guide that shows one before-and-after call, since most of the work is mechanical and an example removes the reading.

The shape of a first integration: how you get a credential, which single endpoint proves the credential works, what a minimal successful call looks like end to end, and what to do with the identifier that comes back. It also holds the policies that span every endpoint - how authentication is scoped, what your retry and idempotency contract is, what pagination looks like, how errors are shaped - because repeating those on ninety generated pages guarantees ninety copies that disagree. None of it can be generated, none of it is covered by a test, so it needs a named owning team and a review date, or it becomes the stale part of an otherwise current reference.

Extract them from files that compile and run, rather than typing them into Markdown. A sample living in a test file, pulled into the page by an include or a region marker, breaks the build when the API changes, which is the only mechanism that has ever worked. Where extraction is impractical, the fallback is a scheduled job that executes the samples against a live sandbox and files issues on failure. What does not work is review: a sample is the part of a page a reviewer reads least carefully because it looks like data rather than prose, and it is the part readers copy most.

Placement, not wording, is what usually fails.

<!-- Before: complete, correct, and read too late -->
Run `svc reset --hard` to return the cluster to a clean state.

> Note: this drops all tenant data and cannot be undone. Take a snapshot first.

<!-- After -->
Before resetting, take a snapshot - `svc reset --hard` permanently drops all
tenant data and cannot be undone.

1. `svc snapshot create --name pre-reset`
2. `svc reset --hard`

No information was added. The only change is that the sentence the reader needed first now comes first, and that is most of what editing a procedure consists of.

The reason placement matters more here than anywhere else is that readers of a procedure execute as they read. They are not reading the page and then acting; they are running each line as their eye reaches it. A caution positioned after the command has been read by someone whose data is already gone, no matter how strongly it is worded or how visually distinctive the callout style is.

The second change is turning one sentence containing two actions into two numbered steps. A step should be one action, because a reader following along tracks their position by the step number, and a step containing two commands loses that.

What was deliberately not changed is the tone. The original was not too soft; it was in the wrong place. Rewriting a correct warning into stronger language while leaving it below the command is the edit that feels productive and fixes nothing.

Because it deletes the actor, and in a procedure the actor is the information.

Before: The certificate must be uploaded before the service is restarted.
After:  Upload the certificate, then restart the service.

Before: Permissions are granted by an administrator.
After:  Ask an administrator to grant you the `deploy` role.

The first pair is the common case. The passive sentence is true and leaves the reader unsure whether uploading is their job, the platform team's, or something the installer does. The imperative rewrite answers that by construction, because an imperative has exactly one implied subject - you.

The second pair shows the more expensive version. "Permissions are granted by an administrator" reads as a fact about the world and stops the reader, who now has to work out that this is a thing they must go and request, from whom, and for what. Naming the action and the role converts a description into a step.

Passive is not banned. It is right when the actor is genuinely unknown or irrelevant - "the request is rejected", "the token is signed" - and forcing an actor into those sentences invents one. The rule is narrower than the folklore: in a procedure, prefer the imperative; in reference prose describing what the system does, the system is usually the right subject anyway.

One action, and short enough that a reader can hold it while looking away at a terminal. That means one command or one UI interaction per numbered step, with the expected outcome stated when it is not obvious - "the pod restarts and the readiness probe passes within about a minute" tells the reader whether to wait or to worry. Two commands in one step is the commonest defect, because readers track their position by number and lose it. The corollary is that a procedure with twenty-eight steps is usually two procedures, or one procedure with a script that should exist.

Short sentences with one clause each, consistent terminology with no synonyms for variety, the active voice, and no idiom - "out of the box", "hit the endpoint", "a couple of gotchas" all cost a reader time or accuracy. Prefer the plain verb over the phrasal one where a plain one exists: "delete" not "get rid of", "start" not "spin up". Keep the sentence order matching the action order, since a reader translating as they go loses subordinate clauses that reverse it. The same discipline helps machine translation, which many readers will apply to your page whether you plan for it or not.

At the top, before the first step, as a short list of things that must already be true rather than a narrative. Each entry should be checkable: not "familiarity with Kubernetes" but "a cluster you can run kubectl get pods against", not "appropriate permissions" but "the deploy role in the target workspace". The reason to be that concrete is that an unmet prerequisite is the most common cause of a procedure failing, and a reader who fails at step 4 cannot tell whether they lack a prerequisite or the page is wrong. A stated, checkable prerequisite converts a mystery into a decision.

Because it makes a claim about the reader's experience rather than about the system, and when it is wrong it is insulting at the worst possible moment. A reader who is stuck on the step you described as simple now has evidence that either they are incapable or the documentation is lying, and both readings cost you trust. The same applies to "just", "obviously", "of course" and "easy". They add no information, which is the practical test: delete the word and the sentence means exactly what it did. Where the intent was genuinely to signal low effort, say something checkable instead, such as how many steps it takes.

Ask whether the structure is the point. A sequence between three parties, a state machine with an awkward transition, a lifecycle with a real branch - those are things prose describes badly because the reader has to reconstruct a shape from a list. A diagram that restates a sentence is worse than the sentence, because it costs the reader a context switch and costs you maintenance forever. The other test is upkeep: a diagram is invisible to every check in your pipeline, so it rots exactly like a screenshot. If it will need to change every release, write the sentence or generate the diagram from something authoritative.

Triage before commenting, because conflating the three buckets is what makes a docs review feel like a verdict on the author.

bucket             what is in it                          what you do
-----------------  -------------------------------------  --------------------------
1 reader will      a wrong claim, a missing               BLOCK, and give the
  fail             prerequisite, steps in the wrong       reason as a reader
                   order, a warning below its command     outcome

2 mechanical       heading levels, banned words,          FIX in a commit on their
  style            terminology, prose where numbered      branch, and name the rule
                   steps belong                           once with a link

3 voice            sentence rhythm, your preferred        LEAVE IT
                   synonym, mild wordiness

Bucket one you find by running the procedure on a clean environment in the order given, not by reading it. That is the difference between a docs review and a copy edit, and it catches the defect a subject-matter expert reliably ships: a page that works only where the credentials, feature flag and local database already exist.

Bucket two is fixed rather than commented because a comment per instance produces a wall of twenty notes for a problem that is one rule. Push a commit to their branch, then leave a single comment saying which rule you applied and where it is written down.

Bucket three is where discipline is required, because these are the comments easiest to write. Twenty-two comments of which eighteen are style reads as a judgement, and the predictable result is not a better second draft but an engineer who concludes documentation belongs to someone else and changes the system silently next time. You traded an awkward page for an absent one.

Because the scarcest input to a documentation set is contributions from people who understand the system, and a review that reads as a rejection reduces the supply. The engineer does not conclude that they should write better; they conclude that writing is the writer's job and that submitting a page costs them an afternoon of comma negotiation. Next time the behaviour changes, nothing is written at all. The deliverable of a docs review is therefore two things - a page a reader can follow, and an author who sends the next one - and a comment that serves neither should not be written.

Anything statable as a checkable rule: heading order and levels, banned words, approved terminology, sentence length ceilings, required sections for a page type, link syntax, code-fence languages. Moving those to a tool changes their social meaning, which is the real benefit. A rule enforced by a script is a fact about the repository; the same rule delivered by a person is an opinion the author may argue with, and often will. What must stay human is judgement that cannot be expressed as a rule - whether a page is aimed at the right reader, whether an explanation is actually explaining, whether a warning is in the right place.

Say so, and change the review you are doing. You can still verify internal consistency, check that every referenced flag and field exists in the code or the spec, confirm the prerequisites are checkable, and read for the gaps a stranger would hit. What you cannot do is claim the procedure works, so the review should route that verification to someone who can - a second reviewer with access, or a request that the author paste the terminal transcript into the pull request. The failure mode is approving on the strength of the prose, which is how a well-written and untested procedure gets published with your name on it.

To convert the commonest blocking review comment into a structural default. A contributor handed an empty file writes whatever shape they last read; a contributor handed a page with ## Prerequisites, ## Steps and ## Verify that it worked already in it fills them in. That gets you consistency without review effort and without anyone reading a style guide, which is the only mechanism that scales past a handful of contributors. The cost is that a template invites padding - a heading present because the template had it, with a paragraph underneath saying nothing - so a template should be short and its sections should be plainly optional where they are.

By making most of it mechanical and accepting the rest. Terminology and formatting are enforceable by tooling and account for the majority of what readers perceive as inconsistency. Page shape is handled by templates. What is left - register, rhythm, how direct the prose is - cannot be enforced and should not be litigated per pull request; it converges when a small number of pages are written well and visibly held up as the model, and when one editor passes over high-traffic pages periodically. A docs set where every contributor's voice is detectable but every page uses the same words for the same objects reads as consistent. The reverse does not.

Separate what the sentence claims from how it is built, and only touch the second where it changes what a reader does. Reordering so the warning precedes the command, splitting a two-action step, and turning a passive description into an imperative all change behaviour and are worth making. Substituting your preferred synonym, tightening a sentence that was merely long, and reshaping a paragraph into your habitual pattern do not. A useful check before pushing an edit is to ask what a reader would have done differently without it. If the answer is nothing, the edit is taste, and taste spent on someone else's draft is charged to the relationship.

Support tickets whose answer is already on a page, which means the page exists and is not being found or not being understood. Search queries with no click, or with an immediate second query, which locate the vocabulary mismatch between your headings and your readers' words. Repeat questions in a community channel. Exit from a tutorial concentrated at one step, which points at a missing prerequisite at that step. And the flat one people forget: pages with no owner and no review in a year, which are failing whether or not anyone has complained yet. Each of those is actionable, which is what distinguishes them from traffic.

Scoring is only useful if each row implies a specific repair.

Page: "Rotate a service credential"        Scored: 2026-07-30

dimension     signal measured                 this page   repair implied
------------  ------------------------------  ----------  -----------------------
Findable      search clicks / impressions     4%          retitle using the
                                                          reader's words

Correct       last verified against a build   14 months   re-run the procedure

Complete      steps failing on a clean        2 of 9      add the missing
              environment                                 prerequisites

Actionable    documented errors carrying a    3 of 11     write the action for
              "what to do"                                the other eight

Owned         owning team in frontmatter      none        assign it, or delete
                                                          the page

Read it as a queue rather than a grade. A 4% click-through on impressions that are already happening means the page ranks and the title does not match what the reader thinks they need, which is twenty minutes of work with a measurable result. Two of nine steps failing on a clean environment is a different order of problem and outranks everything else in the table, because a procedure that fails partway costs the reader more than no procedure at all.

The ownership row is the one that decides whether the others get fixed. Every repair above needs a person, and an unowned page produces findings nobody accepts. That is also why "delete the page" belongs in the column: an unowned, unverified page with low traffic is a liability, and removing it is a legitimate outcome that teams treat as failure.

What is deliberately absent is anything about page views, satisfaction votes or word count. None of them name a repair.

The loop matters more than the tooling, because the expensive step is the one teams leave out.

flowchart TD
  T[Ticket resolved] --> Q{Was the answer already documented}
  Q -->|No| W[Write or extend the page]
  Q -->|Yes, not found| R[Retitle and relink]
  Q -->|Yes, not understood| E[Rewrite for the reader who failed]
  W --> L[Link the page in the ticket reply]
  R --> L
  E --> L
  L --> M[Tag the ticket with the page]

The branch on the right is the whole point. "Was it already documented" splits one complaint into three completely different repairs, and skipping the question means every ticket becomes a request to write something new - which is how a docs set grows a fourth page about authentication.

The last two boxes are what makes the loop measurable. If support replies link the page and tag the ticket with it, you get a per-page count of tickets that a page failed to prevent, ranked by volume. That is the most useful documentation metric most teams could have and almost none collect, because it requires a habit in a different team rather than a dashboard.

The awkward part is that the "not understood" branch is the most common and the least often chosen, since it requires admitting that a page you wrote did not work on someone who found it.

Because both directions are ambiguous and the desirable one is often short. A long visit may mean the page was thorough and absorbing, or that the reader could not find the parameter they came for. A short visit may mean they found it in eight seconds, which is a success, or that the page was clearly wrong for them. Nothing in the number distinguishes those, and optimising it pushes towards longer pages, which is the wrong direction for reference. Metrics worth having name a failure that implies a repair - a search with no click, a ticket whose answer was already written down, a step where tutorial readers stop.

A scheduled report of pages whose last verified date is older than a threshold, grouped by owning team and sorted by traffic. The two design decisions are what makes it work or not. Verified must be a deliberate field rather than the commit date, or a typo fix marks a page as checked. And the report must be addressed to teams rather than published as a dashboard, because an unaddressed list of stale pages is information nobody has accepted. The useful output is not "everything is current" - it never will be - but a small ranked queue where high-traffic stale pages are visible above low-traffic ones.

Watch someone do it. Five people from the intended audience, on a clean environment, told to narrate and not helped, will find more than any analytics setup: the step where the wording is ambiguous, the prerequisite you assumed, the point where they lost confidence about whether it had worked. Where observation is impractical, the proxies are the step at which readers stop, whether the final verification step is reached, and whether the tutorial's own commands still run in CI. What tells you nothing is whether readers rated it helpful, since the people who abandoned it at step 3 do not vote.

The words your readers use, which are frequently not the words your product uses. Queries with impressions and no clicks show a title mismatch on a page that already ranks, which is the cheapest fix available. Queries with no results at all show either a genuinely missing page or a synonym your search index does not know, and those are different repairs. Repeated searches within one session mean the first result was wrong. On-site search is more valuable than external search here despite lower volume, because those readers already decided your docs should have the answer.

Three things, in roughly this order. Whether you can learn an unfamiliar technical thing fast enough to write about it, which is usually probed by making you ask questions about a system you have not seen. Whether you make structural decisions for a reader rather than for a subject - given a page, what you would split, cut or move. And whether you can work with engineers, which is tested through the review scenarios, because the failure mode of the role is a writer whom nobody wants to send a draft to. Prose quality is checked, but it is table stakes rather than the differentiator.

Say what you are doing and why, in the order that matters, rather than starting at the sentences. Read for the reader first: who is this for, what are they trying to do, is anything here going to make them fail. Then flag the structural findings - a missing prerequisite, a warning below its command, lookup material buried in narrative - and only then touch wording. Interviewers are watching whether you can distinguish an edit that changes what a reader does from an edit that reflects your taste, and a candidate who opens by fixing commas has answered that already.

Decide what the deliverable is before writing it, and say so. An endpoint needs a reference entry with the shape and every error's meaning and action, plus enough surrounding prose for a first successful call - how to authenticate, what to call first, what to do with what comes back. Write down the questions you would have asked the engineer and your assumptions where you could not ask, because a take-home with an explicit assumptions section demonstrates the working habit the job needs. Include one error case with a genuinely awkward semantic, since that is where the difference between describing and documenting shows.

Talk about a decision, not a page. The strong version names a specific problem you found, what you changed, and how you knew it worked.

Page: "Rotating service credentials", internal platform docs.

Problem   Ten tickets in a quarter, all from teams who had rotated a
          credential and dropped in-flight requests. The page was correct.
Cause     The overlap window was explained in paragraph six, after the
          steps. Readers executed as they read and never reached it.
Change    Moved the overlap requirement into a prerequisite, made the old
          credential's grace period step 1, added a verification step that
          proves both credentials are live before revoking.
Result    Two tickets the following quarter, both about a different thing.
          Support started linking the page instead of writing the steps out.

The shape is what matters, not the numbers. A candidate who says "I rewrote our credentials page and it is much clearer now" has made an unfalsifiable claim; the version above states a symptom, a diagnosis, an intervention and an observation, which is the same structure an engineer uses for a bug and is recognised as competence for the same reason.

Note that the diagnosis is not "the writing was bad". The page was accurate and well written, and it failed for a structural reason - correct information in a position the reader never reached. Being able to name that class of failure is the single most useful thing to demonstrate in this round.

Do not bring a portfolio piece you cannot discuss this way. One page with a diagnosis behind it beats six samples with none, and the interviewer will ask why you made a choice, not whether the prose is smooth.

By not requiring them to. The realistic answer is that you extract rather than commission: a thirty-minute recorded conversation gets you what a three-week wait for a draft does not, and you write it and send it back for a correctness check, which is a task engineers accept because it is bounded and plays to what they know. Where they do write, you make the cost low - a template with the sections already in it, a linter instead of style comments, a review that fixes mechanics rather than listing them. What signals inexperience is proposing a process that requires engineers to care about documentation as much as you do.

Take the question seriously, because the honest answer is that it changes the work. Drafting, summarising, restructuring and producing a first pass over a reference page are now cheap, which removes a real part of what junior documentation work used to be. What is not cheap is knowing what is true, which requires running the procedure, and deciding what a reader needs, which requires knowing who the reader is. The volume of plausible, fluent, unverified documentation is going up, and that makes verification and structural judgement the scarce parts. A candidate who claims nothing has changed reads as uninformed; one who says the drafting share of the job has shrunk and the reviewing share has grown reads as someone who has been paying attention.

By demonstrating it in the interview rather than asserting it. Ask the questions a writer asks: who uses this, what breaks most often, what do people get wrong about it, what would happen if this step were skipped. Then feed back a one-sentence model of the system and let them correct it, which is exactly the loop you would run with a subject-matter expert and is visible as a skill. Claiming to be a fast learner is unverifiable; asking the third question, the one that shows you noticed a gap in the second answer, is not. Interviewers remember the candidate who found a hole in their own explanation.

A strong answer refuses to treat this as a writing problem until it has found out which failure it is, because there are four and they have different repairs. Nobody can find it, which is a title, a heading and a navigation problem and shows up as impressions without clicks. They find it and it is the wrong mode - someone mid-incident landed on an explanation - which is an information architecture problem. They find it and cannot use it, which is usually structural: lookup material buried in prose, or a warning positioned after the action. Or nobody needs it, in which case the correct action is deletion, and the willingness to say so is a real signal.

The weak answer starts rewriting. It improves sentences on a page whose problem was that its title used the product's vocabulary rather than the reader's, and then reports the page as fixed with nothing measured. The other weak answer blames readers for not reading, which ends the investigation before it starts. If you take one habit into this round, take the habit of asking what evidence exists that the page is being reached at all.