# Technical Writing Rules

## Structure

1. **Lead with the answer or the outcome.** Not the background, not the approach, not a
   restatement of the question. If something could not be verified, say that first.
2. **One idea per sentence.** About twenty words. If you need a semicolon, you needed
   two sentences.
3. **Cut by leaving things out, not by compressing.** A dense paragraph is not short,
   it is hard.
4. **Use a list for parallel items only**, findings, steps, options. A line of argument
   stays in prose. A single point is a sentence, not a bullet.
5. **No headings under about 500 words.**

## Honesty

6. **Never state as done what you did not verify.** "Tests pass" means you ran them and
   read the output.
7. **Report failures first and plainly.** If a step was skipped, say which and why.
8. **Distinguish what you know from what you infer.** "The config sets a 30s timeout"
   and "the timeout is probably why it failed" are different claims.
9. **Do not hedge what you are sure of.** "It may be possible that this could
   potentially cause" is four hedges around one fact. If you know, say it.
10. **Do not manufacture certainty either.** If you are guessing, the sentence starts
    with a word that says so.

## Voice

11. **Say what a thing is, not what it is not.**
12. **Prefer the concrete noun to the category.** "The retry loop" beats "the relevant
    functionality".
13. **No filler openers.** Delete "It is worth noting that", "Importantly", "In order
    to", "It should be mentioned".
14. **No closing offer.** Stop when the content stops. "Let me know if you would like
    me to elaborate" adds nothing.
15. **Do not praise the question or the code before answering.**

## Precision

16. **Name the thing once, then use the same name.** Switching between "the handler",
    "the endpoint" and "the route" for one object makes the reader do bookkeeping.
17. **Expand an uncommon acronym on first use.**
18. **Numbers go where they can be compared**, a table or their own line, not buried
    mid-sentence.
19. **Code in code blocks. Prose in prose.** Name a file or function only when the
    reader has to go there.

## Commits and PRs

20. **The commit subject says what changed and why**, in one line, imperative mood.
    Not "fixes" or "updates".
21. **The body explains what the subject cannot**: the constraint, the alternative
    rejected, the thing that will surprise the next reader.
22. **A PR description says what a reviewer needs to review well**: what changed, what
    to look at hardest, what you are unsure about.

## Before and after

> Before: It is worth noting that the implementation may potentially have some issues
> with regards to how errors are being handled in certain edge cases.

> After: The retry loop swallows connection errors. A dropped connection looks
> identical to a successful empty response.