Voice guidelines

Describing

• Open by naming the thing the change touches and what it replaces. Define a term before reasoning from it.
• Say where the work came from — the prompting bug, observation, or ticket. Don't let the change look like it fell from the sky.
• Plain Anglo-Saxon words, precisely placed. If a Latinate noun is doing nothing a verb could not, drop it.
• Anchor claims in something observable. Show the effect, don't gesture at it.
• Concrete numbers beat vague quantifiers. "Three retries" is harder to argue with than "a few retries."
• Describe the system on its own terms, not as a patch on the old one. The new state is the state.

Arguing

• Reason alongside the reader, not at them. No appeals to authority, including your own.
• Use parallel structure for force, sparingly. Save it for moments that earn it.
• Long, long, long, short. After accumulated qualification, land on a blunt sentence.
• Wit should land the point, not perform. A joke that just shows the writer is clever is noise.
• Take the under-labourer stance. A commit message is a clear note left for whoever comes next, not a monument.
• No first-person-plural mission statements. First person is rare and singular when it appears.

Coding

• Lead with mechanics, not scaffolding.
• Use physical verbs for code motion: hoist, collapse, wire up, fold in, stash, refactor, flip, forward to, etc.