1
# Technical Writing Rules
2
3
## Structure
4
5
1. **Lead with the answer or the outcome.** Not the background, not the approach, not a
6
   restatement of the question. If something could not be verified, say that first.
7
2. **One idea per sentence.** About twenty words. If you need a semicolon, you needed
8
   two sentences.
9
3. **Cut by leaving things out, not by compressing.** A dense paragraph is not short,
10
   it is hard.
11
4. **Use a list for parallel items only**, findings, steps, options. A line of argument
12
   stays in prose. A single point is a sentence, not a bullet.
13
5. **No headings under about 500 words.**
14
15
## Honesty
16
17
6. **Never state as done what you did not verify.** "Tests pass" means you ran them and
18
   read the output.
19
7. **Report failures first and plainly.** If a step was skipped, say which and why.
20
8. **Distinguish what you know from what you infer.** "The config sets a 30s timeout"
21
   and "the timeout is probably why it failed" are different claims.
22
9. **Do not hedge what you are sure of.** "It may be possible that this could
23
   potentially cause" is four hedges around one fact. If you know, say it.
24
10. **Do not manufacture certainty either.** If you are guessing, the sentence starts
25
    with a word that says so.
26
27
## Voice
28
29
11. **Say what a thing is, not what it is not.**
30
12. **Prefer the concrete noun to the category.** "The retry loop" beats "the relevant
31
    functionality".
32
13. **No filler openers.** Delete "It is worth noting that", "Importantly", "In order
33
    to", "It should be mentioned".
34
14. **No closing offer.** Stop when the content stops. "Let me know if you would like
35
    me to elaborate" adds nothing.
36
15. **Do not praise the question or the code before answering.**
37
38
## Precision
39
40
16. **Name the thing once, then use the same name.** Switching between "the handler",
41
    "the endpoint" and "the route" for one object makes the reader do bookkeeping.
42
17. **Expand an uncommon acronym on first use.**
43
18. **Numbers go where they can be compared**, a table or their own line, not buried
44
    mid-sentence.
45
19. **Code in code blocks. Prose in prose.** Name a file or function only when the
46
    reader has to go there.
47
48
## Commits and PRs
49
50
20. **The commit subject says what changed and why**, in one line, imperative mood.
51
    Not "fixes" or "updates".
52
21. **The body explains what the subject cannot**: the constraint, the alternative
53
    rejected, the thing that will surprise the next reader.
54
22. **A PR description says what a reviewer needs to review well**: what changed, what
55
    to look at hardest, what you are unsure about.
56
57
## Before and after
58
59
> Before: It is worth noting that the implementation may potentially have some issues
60
> with regards to how errors are being handled in certain edge cases.
61
62
> After: The retry loop swallows connection errors. A dropped connection looks
63
> identical to a successful empty response.
64