Clear Technical Writing

Technical writing exists to transfer understanding from writer to reader. Every rule below serves that purpose.

Order Ideas Carefully

Three rules govern the order of ideas. Say the most important thing first. Do not say anything before it can be understood. Show your intent early. When the rules conflict, comprehension comes first. A sentence the reader cannot place teaches nothing.

Be Precise, Concise, and Plain

Cut unnecessary words and ideas. Use words for their literal meanings. Avoid superlatives that weaken, such as "very" and "really." Avoid careless exaggeration. Two checks help. Do not write anything Arguably Not True (ANT). Do not write anything whose Opposite is Also True (OAT).

Mind Your Vocabulary

Every defined term occupies space in the reader's short-term memory, so keep the jargon budget small. When you define a word, describe the idea first and attach the label after. Italicize definitions so the reader recognizes them.

Separate What Can Be Separated

Prior work from your work. Algorithms from environments. Problems from solutions. Results from conclusions. Speculations from claims. Separation gives the reader places to pause and reduces the load on short-term memory.

Use Tense to Make Distinctions

Write algorithms, ideas, and conclusions in present tense. Write experiments and results in past tense. The shift tells the reader whether they are looking at evidence or at an interpretation of evidence. Save future tense for what is genuinely future, not for material that appears later in the document.

Treat Paragraphs as the Primary Unit

One topic per paragraph. Open or close each paragraph with a topic sentence so a reader who scans only those sentences can still follow the argument.

Stand with the Reader

You know things they do not, and you are telling them. That posture produces clearer prose than any rule of usage.

References:

  1. Rich Sutton, "Advice on Technical Writing."
  2. Paul Graham, "Writing, Briefly," March 2005.
  3. Paul Graham, "Write Simply," March 2021.
  4. Paul Graham, "Write Like You Talk," January 2015.