tech-writing

Technical Writing

Apply Google's Technical Writing curriculum to make technical prose clear, concise, and well-structured. Adapted from https://developers.google.com/tech-writing (CC BY 4.0).

When this applies

Documentation, READMEs, PR/commit descriptions, design docs, code comments meant for humans, and technical explanations or answers. If you are about to produce more than a sentence or two of technical prose, run the workflow below.

Workflow

1. Identify the audience and the artifact. Who reads this, and what do they already know? A PR description targets reviewers; a README targets new users. Match vocabulary to the audience and beware the curse of knowledge (you know things they do not).
2. Draft using the cheat-sheet rules below.
3. Run the self-edit checklist before declaring the text done.
4. Consult references/ for depth on any rule you are unsure about:
   • references/technical-writing-one.md — sentence/word/paragraph/list fundamentals
   • references/technical-writing-two.md — self-editing, structuring long docs, illustrations, sample code, writing for LLMs
   • references/error-messages.md — writing helpful error messages
   • references/accessibility.md — writing accessible technical content

Cheat-sheet (apply while drafting)

• One idea per sentence. Split long sentences; convert sentences with "and"/"but" joining unrelated ideas into separate sentences or a list.
• Use strong, precise verbs. Replace weak verb + abstract noun ("perform an analysis") with one verb ("analyze"). Cut "there is / there are" where a real subject and verb work better.
• Prefer active voice. "The system sends a request" beats "A request is sent." Use passive only when the actor is unknown or irrelevant.
• Define each term once, then use it consistently. Do not rename the same concept. Expand an acronym on first use; reuse one term, not synonyms.
• Reduce filler adjectives and adverbs. Show with specifics instead.
• Use lists and tables for parallel items. Numbered list = sequence; bulleted list = unordered set; table = items with shared attributes. Keep list items parallel in form.
• Start each paragraph with a topic sentence. One topic per paragraph; 3–5 sentences. Answer what / why / how.
• Disambiguate pronouns. Replace an unclear "it"/"this"/"that" with the noun.

Self-edit checklist (run before finishing)

• Did I state the audience-relevant point first?
• Is every sentence one idea? Any sentence over ~25 words I can split?
• Any passive voice I can make active?
• Any weak verbs ("is", "make", "perform", "do") I can strengthen?
• Every term used consistently? Every acronym defined on first use?
• Any pronoun ("it", "this", "that") whose referent is unclear?
• Would a list or table read better than this prose?
• Does each paragraph open with its main point?
• Did I cut filler ("very", "really", "in order to", "basically")?
• Read once more as the reader: anything assumed that they would not know?