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 — pull request, issue, and commit text, docs, READMEs, code comments, release notes, and messages.

The guide of record is the lab’s Principles of Scientific Writing (PSW): https://morrison-lab.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 is 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 — pull request and issue descriptions, commit bodies, README, doc, and vignette text, or long answers — self-check it and cut the tells. Apply the same catalog when reviewing someone else’s prose too:

  • 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 is worth noting that”, “importantly”), hedging stacks, hollow “in conclusion” restatements.
  • Structural and 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 do not 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.

23.4 Show, Don’t Tell

The adage “show, don’t tell” (or “a picture is worth a thousand words”) is a foundational communication principle across research manuscripts, technical documentation, and oral presentations.

Whenever conveying complex concepts, workflows, data patterns, or system architectures, favor concrete visual evidence and direct demonstration over dense verbal exposition.

23.4.1 In scientific manuscripts and reports

  • Lead with clear figures and tables: Instead of describing multi-step analytical pipelines or multi-group comparative trends in lengthy paragraphs, present the data in a well-labeled plot or diagram.
  • Support visuals with interpretation, not repetition: Use the narrative text to guide the reader through the key insights and takeaways of a figure rather than exhaustively listing every number already legible in a table or plot.
  • Use diagrams for conceptual models: Directed acyclic graphs (DAGs), CONSORT flow diagrams, and workflow schematics clarify methodological structures much faster than textual descriptions alone.

23.4.2 In conference and lab presentations

  • Minimize text on slides: Audiences cannot read dense bulleted paragraphs while simultaneously listening to a speaker. Replace text-heavy slides with clean visuals, diagrams, or summary charts.
  • Highlight key focal points: Use callouts, annotations, or sequential visual reveals to focus attention on the specific relationship being discussed.
  • Demonstrate rather than assert: When presenting software tools or analytical pipelines, show live output, reproducible code snippets, or screenshots rather than merely listing features.