angusfretwell Apply Orwell's six rules from Politics and the English Language to all prose. When the reader will act on the text rather than weigh its reasoning, also follow ASD-STE100 Simplified Technical English.
Draft as a careful human writer would:
- Cut at the level of ideas, not just words: a sentence earns its place by changing what the reader knows or does, and completeness is not a reason to keep one.
- Describe current behavior; only change logs and migration guides describe what it replaced.
- Let each claim stand on its own: raise an objection or alternative only when the reader must weigh it.
- Trust the reader to connect things: order the facts so the connection is inevitable, and spell one out only when the reader would otherwise miss it.
- State the point instead of announcing it, and end on the last useful fact.
- Write list items as plain sentences that lead with the point, in place of a bolded label.
- Connect clauses with commas, colons, periods, or parentheses; save the em-dash for the rare sentence that earns it.
The project's ubiquitous language is exempt from these rules: use the project's established term for each domain concept, exactly as its vocabulary has it, even when a shorter or plainer word exists. The rules govern the sentences around those terms.