Technical writing

Documentation and engineering writing for developers and users: the Diátaxis framework, docs as code, style guide essentials, READMEs, procedures, reference and API docs, design docs, RFCs, ADRs, commit messages, changelogs, comments, error messages, runbooks and postmortems, diagrams, terminology, accessibility and how to measure docs quality. Sentence-level rules are in clear writing; proposals and decision memos in persuasive writing. Architecture itself is in system design.

Diátaxis: four kinds of documentation

Daniele Procida's Diátaxis framework says documentation serves four distinct user needs, and most bad docs come from mixing them. The compass classifies any piece of content with two questions: does it inform action (practical steps, doing) or cognition (theoretical knowledge, thinking)? Does it serve the acquisition of skill (study) or its application (work)?

Common failure patterns and fixes:

Docs as code

Docs as code (a term popularised by the Write the Docs community) means writing documentation with the same tools and workflow as code.

Limits: docs as code works for engineers; non-engineering writers may need a friendlier editor on top, and nothing in the pipeline checks whether the docs actually answer the user's question.

Style guide essentials

Adopt an existing style guide and record only your exceptions. The two most used in software are Google's and Microsoft's.

Google developer documentation style guide highlights:

Microsoft Writing Style Guide "top 10 tips" add: "Use bigger ideas, fewer words"; "Write like you speak"; use contractions ("it's", "you'll"); "Get to the point fast"; "Be brief"; "When in doubt, don't capitalize"; no end punctuation on titles and headings; "Remember the last comma" (the Oxford comma); one space after full stops. Microsoft's own before/after: "If you're ready to purchase Office 365 for your organization, contact your Microsoft account representative." → "Ready to buy? Contact us."

README anatomy

A README answers, in order: what is this, why should I care, how do I use it, how do I help. The first screen decides whether anyone reads further.

Test: a new teammate on a clean machine gets from git clone to a running example using only the README. Time it, and fix every place they stall.

Writing procedures

Procedures (how-to guides, runbook steps, setup instructions) fail when the reader cannot tell what to do, in what order, and whether it worked.

## Rotate the database password
 
Before you begin: admin access to the secrets manager;
a maintenance window is not required.
 
1. Create a new password:
   `openssl rand -base64 32`
2. Add it as a second credential in the database:
   `ALTER ROLE app WITH PASSWORD '<new>';` ...
3. Update the secret `db/app-password` to the new value.
4. Restart the API pods: `kubectl rollout restart deploy/api`
   Expected: all pods Ready within 2 minutes.
5. Verify: `curl -f https://api.example.com/health`
   returns `{"db":"ok"}`.
 
If step 4 pods crash-loop: the secret did not propagate.
Roll back by restoring the previous secret version.

Reference and API docs

Reference docs are looked up, not read. Make them complete, consistent and predictable: every entry has the same shape.

Rules: generate the skeleton from the source of truth (OpenAPI spec, types); write descriptions by hand; describe every parameter including the obvious ones; state units (ms, bytes, cents) and formats (ISO 8601, UTC); give realistic example values, not foo and string.

Design docs

A design doc records the problem, the chosen design and, above all, the trade-offs, before implementation. Malte Ubl's "Design Docs at Google" (2020): "The design doc documents the high level implementation strategy and key design decisions with emphasis on the trade-offs that were considered during those decisions." Rule #1 in his words: "Write them in whatever form makes the most sense for the particular project." The structure that has established itself:

Length: "around 10-20ish pages" for a larger project; a 1–3 page "mini design doc" for incremental work. Don't write one when the solution is not ambiguous: if the doc is really an implementation manual (Ubl's phrase) with no trade-offs, you should have just written the code.

Lifecycle (Ubl): creation and rapid iteration → review → implementation and iteration (update the doc when the design changes) → maintenance and learning (re-read your own docs a year or two later).

RFCs

RFC (request for comments) processes circulate a proposal for broad feedback before a decision. The name comes from the IETF series that began with RFC 1 in 1969; open-source projects run their own versions (Rust RFCs, Python PEPs, React RFCs), and many companies use "RFC" for what Google calls a design doc.

Normative keywords. RFC 2119 (1997) defines MUST, MUST NOT, SHOULD, SHOULD NOT and MAY for requirement levels; RFC 8174 (2017) clarifies they carry that meaning only in capitals. Use them in specs and APIs so "should" is not read as "must".

Architecture decision records

Michael Nygard, "Documenting Architecture Decisions" (Cognitect blog, 15 November 2011), proposed keeping "a collection of records for 'architecturally significant' decisions: those that affect the structure, non-functional characteristics, dependencies, interfaces, or construction techniques." Each ADR is a short text file in the repo, numbered sequentially; numbers are never reused, and reversed decisions are marked superseded rather than deleted.

He adds: "The whole document should be one or two pages long", written "as if it is a conversation with a future developer", in full sentences because "Bullets kill people, even PowerPoint bullets."

Commit messages

Chris Beams, "How to Write a Git Commit Message" (2014), "The seven rules of a great Git commit message":

His test for rule 5: a subject line should complete "If applied, this commit will ___". "Refactor subsystem X for readability" passes; "Fixed bug with Y" doesn't.

Fix race condition in session refresh
 
Two tabs refreshing an expired token at the same time both
sent the old refresh token; the second request failed and
logged the user out.
 
Serialize refreshes behind a single in-flight promise so
concurrent callers share one request.
 
Fixes #482

Conventional Commits (v1.0.0) adds a machine-readable prefix: <type>[optional scope]: <description>, an optional body and optional footers. The spec defines only two types: fix: (correlates with a SemVer PATCH) and feat: (a MINOR). A breaking change is marked with a BREAKING CHANGE: footer or a ! after the type/scope (a MAJOR). Other types are allowed; @commitlint/config-conventional (based on the Angular convention) recommends build, chore, ci, docs, style, refactor, perf and test.

feat(api)!: require email verification before login
 
BREAKING CHANGE: unverified accounts now receive 403 from
POST /v1/sessions. Existing sessions are not affected.

Beams's capitalized subject and Conventional Commits' lowercase type: prefix conflict; pick one convention per repo and enforce it with a commit-msg hook.

Changelogs

Keep a Changelog (keepachangelog.com): "Changelogs are for humans, not machines." Its guiding principles: an entry for every version; group the same types of change; linkable versions and sections; latest version first; show the release date of each version; say whether you follow Semantic Versioning.

Keep an Unreleased section at the top. Use ISO 8601 dates (2026-09-26). Don't dump the commit log: "they're full of noise". "If you do nothing else, list deprecations, removals, and any breaking changes in your changelog."

Write entries for users, not for the team: "Fixed: CSV export no longer drops rows with commas in the name" beats "Fixed: escape bug in exporter (#1234)".

Code comments and docstrings

Comments explain why; code explains what. If a comment restates the code, delete it; if the code needs a comment to explain what it does, try renaming or restructuring first.

Docstrings document the public interface: what it does, parameters, return value, errors, and an example. Python's PEP 257 asks for a one-line summary written as a command ("Return the…"); JSDoc/TSDoc use @param, @returns, @throws.

Pick one style per project. >>> lines in a docstring are runnable examples: python -m doctest file.py checks that they still print what they say.

/**
 * Returns the price in cents after applying the coupon.
 *
 * @param priceCents - list price in cents; must be >= 0
 * @param coupon - percentage (0-100) or fixed amount
 * @returns discounted price, never below 0
 * @throws RangeError if the percentage exceeds 100
 */
export function applyCoupon(
  priceCents: number,
  coupon: Coupon,
): number { /* ... */ }

def apply_coupon(price_cents: int, coupon: Coupon) -> int:
    """Return the price in cents after applying the coupon.
 
    Args:
        price_cents: List price in cents; must be >= 0.
        coupon: A percentage (0-100) or a fixed amount.
 
    Returns:
        The discounted price, never below 0.
 
    Raises:
        ValueError: If the percentage exceeds 100.
 
    Examples:
        >>> apply_coupon(1000, Percent(25))
        750
        >>> apply_coupon(500, Fixed(800))
        0
    """
    if isinstance(coupon, Fixed):
        return max(price_cents - coupon.cents, 0)
    if coupon.value > 100:
        raise ValueError("percentage exceeds 100")
    # round(), not int(): int() truncates 749.99 to 749
    return round(price_cents * (100 - coupon.value) / 100)

Error messages

A good error message says what happened, why, and what to do next, in the user's language. The UI side (placement, color, inline validation) is in UX/UI design.

Runbooks and postmortems

Runbooks

A runbook is a procedure for a known operational situation, written for someone who is stressed, possibly half-asleep, and not the author.

Postmortems

Google's Site Reliability Engineering book (chapter 15, "Postmortem Culture: Learning from Failure"): "For a postmortem to be truly blameless, it must focus on identifying the contributing causes of the incident without indicting any individual or team for bad or inappropriate behavior." And: "You can't 'fix' people, but you can fix systems and processes." The same logic drives the military after-action review (AAR); see mission command.

Diagrams in docs

Simon Brown's C4 model gives architecture diagrams a shared vocabulary: hierarchical abstractions (software systems, containers, components, code) and one diagram level per abstraction.

Supporting diagrams: system landscape, dynamic (a sequence for one use case) and deployment. The model is notation- and tooling-independent.

Terminology and glossaries

In technical writing, repetition is a feature: a synonym signals a different thing. "Elegant variation" from school essays is a bug here.

Accessibility of docs

Semantics and markup are covered in HTML accessibility.

Measuring docs quality

There is no single docs metric. Combine signals and watch trends, not absolute numbers.

Quality checklist per page: correct, complete for its Diátaxis type, findable, up to date, consistent terms, runnable examples, one clear purpose.

Common mistakes

Templates

README

# project-name
 
One sentence: what it does and for whom.
 
## Why
The problem it solves, in 2-3 sentences. Key features:
- Feature -> benefit
- Feature -> benefit
 
## Quick start
    npm install project-name
    npx project-name init
Expected output: ...
 
## Usage
Common task 1 (with a copy-pasteable example)
Common task 2
Full docs: [link]
 
## Configuration
| Variable | Default | Description |
 
## Development
    git clone ... && cd project-name
    npm install && npm test
 
## Contributing
See CONTRIBUTING.md. Bugs: [issue tracker link].
 
## License
MIT - see LICENSE.

ADR (Nygard format)

# ADR 12: Use Postgres row-level security for tenancy
 
Status: Accepted (2026-09-26). Supersedes ADR 4.
 
## Context
Facts and forces, value-neutral. What constrains us:
tenant isolation is a contractual requirement; queries
are written by 12 engineers across 3 services; an audit
found 2 missing tenant filters last quarter.
 
## Decision
We will enforce tenant isolation with Postgres row-level
security policies on every tenant-scoped table, set
from the session's tenant ID.
 
## Consequences
Positive: a missing WHERE clause can no longer leak data.
Negative: every connection must set the tenant; bulk
admin jobs need a separate role; policies add query cost
(measured at ~3% on hot paths).
Neutral: migrations must include policies (CI check).

Design doc

# [System/feature] design
Author(s) / reviewers / status / last updated
 
## Context and scope
Landscape and what we're building. Facts only. Links.
 
## Goals
- Measurable goal
## Non-goals
- Plausible goal we are explicitly NOT pursuing
 
## Design
### Overview (with system-context diagram)
### APIs (sketch; relevant parts only)
### Data storage
### Key algorithms / flows (pseudo-code only if novel)
 
## Alternatives considered
Option -> trade-offs -> why not chosen.
 
## Cross-cutting concerns
Security, privacy, observability, cost, migration,
rollout and rollback.
 
## Open questions
- Question - owner - due

Runbook

# Runbook: [Alert name]
Owner: [team]   Last reviewed: [date]
 
## What this alert means
[Condition] for [duration]. User impact: [..]. Sev: [..]
 
## Diagnose (first 5 minutes)
1. Dashboard: [link] - look for [..]
2. `[command]` - expected: [..]
3. Recent deploys: `[command]`
 
## Mitigate
- If caused by a deploy: `[rollback command]`
- If traffic spike: [scale / rate-limit steps]
 
## Escalate
After [15] minutes or if [condition]: page [rota/person].
 
## Verify
[Metric] back below [threshold] for [10] minutes.
 
## Follow-up
Open an incident doc; schedule the postmortem.

Bug report

Title: [Component]: [symptom] when [condition]
 
Environment: version/commit, OS, browser, config
Severity: [blocker / major / minor] - [users affected]
 
Steps to reproduce:
1. ...
2. ...
3. ...
 
Expected: ...
Actual: ...   (exact error text, not a screenshot of it)
 
Frequency: always / intermittent (N of M tries)
Logs / trace IDs / screenshots: ...
Workaround: ... (or none)

Pull request description

## What
One or two sentences: the change, from the user's or
system's point of view.
 
## Why
The problem or ticket (#123). Link the design doc/ADR.
 
## How
Key implementation choices and trade-offs; anything
non-obvious a reviewer should look at first.
 
## Testing
How you verified it: tests added, manual steps, results.
 
## Risk and rollout
Migrations, flags, backwards compatibility, rollback.
 
## Screenshots (UI changes)
Before / after.

Postmortem

# Postmortem: [title] ([date])
Status: draft / reviewed   Authors: [..]   Blameless.
 
Summary: [what broke, how long, impact - 2-3 sentences]
Impact: [users, duration, revenue, SLO budget]
Root causes: [contributing causes]
Trigger: [what set it off]
Detection: [how found; time to detect]
Resolution: [what stopped it]
 
Timeline (UTC)
HH:MM  event
 
What went well / What went wrong / Where we got lucky
 
Action items
| Action | Type (prevent/detect/mitigate) | Owner | Ticket |

References

• Diátaxis (opens in a new tab): Daniele Procida's framework; see the compass (opens in a new tab) for the action/cognition × acquisition/application questions
• Write the Docs: Docs as Code (opens in a new tab): the docs-as-code philosophy and tooling
• Google developer documentation style guide: highlights (opens in a new tab): the core rules summarized above
• Microsoft Writing Style Guide: top 10 tips (opens in a new tab): Microsoft's voice and style in brief
• Make a README (opens in a new tab): README guidance and template
• Malte Ubl, "Design Docs at Google" (2020) (opens in a new tab): design doc sections, length and lifecycle
• Michael Nygard, "Documenting Architecture Decisions" (2011) (opens in a new tab): the original ADR format
• RFC 2119: Key words for use in RFCs to Indicate Requirement Levels (opens in a new tab): MUST, SHOULD, MAY; clarified by RFC 8174 (opens in a new tab)
• Chris Beams, "How to Write a Git Commit Message" (2014) (opens in a new tab): the seven rules
• Conventional Commits 1.0.0 (opens in a new tab): machine-readable commit types and SemVer mapping
• Keep a Changelog 1.1.0 (opens in a new tab): changelog principles and change types
• PEP 257: Docstring Conventions (opens in a new tab): Python docstring rules
• Google SRE book, chapter 15: Postmortem Culture (opens in a new tab): blameless postmortems
• The C4 model (opens in a new tab): Simon Brown's four levels of architecture diagrams
• WCAG 2.2 (opens in a new tab): non-text content (1.1.1) and link purpose (2.4.4)
• Clear writing and persuasive writing: the companion sheets