technical-writing

Technical Writing

Use this skill to write for a tired developer who should understand the first read. It is adapted from pstack's technical writing skill under its MIT license, but stands alone and has no pstack only dependencies.

Write Plain English

• Cut words that do no work. Write “to”, not “in order to”. Delete “it is important to note that”.
• Use short, ordinary words unless a technical term adds needed precision. Write “use”, not “utilize”; “move”, not “relocate”; and “help”, not “facilitate”.
• Write the real symbol, file path, flag, command, type, or field name. Do not replace it with a vague description.
• Use one name for one thing throughout the document.
• Do not invent jargon, metaphors, or made up hyphenated phrases. Use words a developer would say out loud.
• Prefer a period to an em dash. Use a new sentence when the thought changes.
• Keep related words close. Put “only” and “not” next to the word they change.
• Break up dense noun strings. Write “the script that checks imports”, not “the import budget check script”.

The rules serve the reader. Rewrite a sentence that sounds mechanical instead of following a rule in a way that makes the sentence worse.

Choose One Document Mode

Pick one mode for each document. Split and link documents when their purposes conflict.

• Tutorial: teach a newcomer by guiding them through a visible result.
• How to guide: help a capable reader complete one task. Keep only the steps and decisions needed for that task.
• Reference: describe facts, options, limits, inputs, outputs, and errors. Mirror the thing being described. Do not persuade or teach.
• Explanation: answer a bounded “why” question with context, constraints, alternatives, and tradeoffs.

Write Clear Sentences

• Address the reader as “you” when giving instructions.
• Use active voice when the actor matters. State who does what.
• Write instructions as commands. Put a condition before the step it controls.
• Put the common case first. Put exceptions after it.
• Give each sentence one instruction or one main thought. Split a sentence that carries more.
• Keep articles and verbs when they make the sentence easier to parse.
• Make each “it”, “they”, “this”, and “which” point to one obvious noun. Repeat the noun when that is clearer.
• Use “both … and”, “either … or”, and “if … then” when they prevent ambiguity.
• Avoid passive constructions such as “the file should be updated”. Write “update the file”.
• Read awkward text aloud. Rewrite it if it still sounds awkward.