Part 7 · 1 chapters · ~8 min

Thinking in Writing

Writing as a thinking tool, the pyramid principle (answer first), one idea per paragraph, making claims checkable, writing to be skimmed, editing for clarity, and the documents that force clear thinking (design docs, decision records, postmortems).

14

Write to think

Writing exposes gaps that conversation hides. A plan that sounds fine aloud often falls apart on the page, which is exactly why written design docs and decision records improve decisions, not just document them (Amazon's six-page memos are built on this idea).

principles
  1. Answer first (Barbara Minto's pyramid principle): the conclusion, then the supporting points, then the detail.
  2. One idea per paragraph, with the idea in the first sentence.
  3. Checkable claims: numbers with sources, specific nouns instead of "some issues".
  4. Write for skimming: headings that carry the argument, tables for comparisons.
  5. Edit: cut every sentence that does not change what the reader will do or believe.
code
before  "We have been seeing some issues with performance that might be related to the database, so we
         think it could be worth looking into options for improving things in that area."
after   "Reporting queries take 40% of database time at peak (pg_stat_statements, last 7 days).
         Moving them to a read replica should cut primary CPU by about a third. Proposal below."

Technical Writing and Influence (course 57) covers the specific documents in depth.