23  Writing

23.1 Writing to Clarify Your Thinking

Writing is a powerful tool for clarifying your thoughts, even before you start searching for answers. When questions or ideas come up, it’s good practice to write them down immediately—this helps you:

  • Organize your thoughts and identify what you actually need to know
  • Articulate the problem more precisely
  • Often realize the answer yourself through the process of writing

As Leslie Lamport, a Turing Award winner and computer scientist, states: “If you think you understand something, and don’t write down your ideas, you only think you’re thinking” (Lamport 2019).

23.2 Plain, Direct Prose

Write user-facing prose in a plain, direct style. This applies to everything a reader sees — PR/issue/commit text, docs, READMEs, code comments, release notes, emails, and chat replies. Apply it by default to your own drafts, not just when asked.

The guide of record is the lab’s Principles of Scientific Writing (PSW): https://d-morrison.github.io/psw/. The rules below operationalize it. When PSW and this guidance disagree, PSW wins.

  • Limit dependent (subordinate) clauses. One per sentence is plenty. When two or more stack up, split the sentence.
  • Cut low-content filler and jargon. Delete words that add no information (“it’s worth noting”, “in order to” -> “to”, “due to the fact that” -> “because”).
  • Prefer plain (Anglish) words over Latin-derived ones (PSW, “Word choice”). “before”, not “prior to”; “needed”, not “necessary”; “use”, not “utilize”. A heuristic, not a purity rule.
  • Prefer simple declarative sentences and active voice. Subject, verb, point. Name the actor, then the action.
  • Join independent clauses with coordinating conjunctions (and, but, so, or) over subordinate constructions. Prefer “X is fast, but Y is correct” over “While X is fast, Y is correct.”

This is a default, not an absolute rule. Keep a clause or a technical term when removing it would lose meaning or precision. Never trade an honest hedge for false confidence.

23.3 Scanning for AI Tells

When AI tools draft or edit prose, the result often carries telltale signs of machine authorship.

Write plainly up front, then scan the draft for AI tells before sending. Before presenting non-trivial prose — PR/issue descriptions, commit bodies, README/doc/vignette text, or a long answer meant as deliverable prose — self-check it and cut the tells. Apply the same catalog when reviewing someone else’s prose too — a PR/MR diff, a doc change, any non-code narrative content — not just your own drafts; flag each tell found rather than waving a plausible-sounding paragraph through unchecked. Watch for:

  • Overused vocabulary: actionable (→ “to act on”), delve, leverage, utilize, tapestry, testament, realm, robust, seamless, holistic, nuanced, multifaceted, pivotal, crucial, “in today’s fast-paced world”, “stands as a testament to”.
  • Rhetorical reflexes: the “it’s not just X, it’s Y” antithesis (the biggest tell), mechanical rule-of-three lists, signposting filler (“it’s worth noting that”, “importantly”), hedging stacks, hollow “in conclusion” restatements.
  • Structural/typographic: em-dash overuse as a default connector, bold-leading **Term:** bullets applied mechanically, emoji section headers, conspicuously uniform paragraph rhythm.
  • Tonal: promotional register, reflexive both-sidesing, vague universals with no concrete names or numbers.

De-slop — cut the filler and the reflexes — but don’t ban words outright or sand the text into a flat, voiceless register. Any single tell is innocent; clustering and mechanical repetition are the signal. Code, terse status lines, and short conversational replies are exempt.