add writing style rule

2026-08-13 01:34:59 +00:00
parent 18f7136959
commit 87806f37c9
1 changed files with 20 additions and 0 deletions
@@ -17,6 +17,26 @@ Known substitutions seen so far:
 Add new ones to this table as they come up.
 ## Writing style
 Write in **Simplified Technical English**, and follow **Zinsser's four
 principles**: clarity, simplicity, brevity, humanity.
 In practice:
 - **Short sentences.** One idea each.
 - **Active voice.** Name who does the thing.
 - **One meaning per word.** Pick a term, then reuse it. Do not vary the wording
  for elegance — in technical writing a synonym reads as a second thing.
 - **Cut the clutter.** Remove any word that carries no weight. Most qualifiers,
  most adverbs, and every phrase that only restates the sentence before it.
 - **Stay warm and human.** A person wrote this, not a manual. Plain does not
  mean cold, and brief does not mean blunt.
 This governs prose written for the user: explanations, summaries, reports,
 commit messages, and comments. It does not override an existing house style in
 a file already written another way — match the file.
 ## Ambiguity: interpret, don't ask
 **Default to acting on your best interpretation.** Work out what was meant from