Technical Writing

technical-writing

Patterns for clear technical writing in documentation, READMEs, API references, and design documents.

Clarity

One idea per sentence. One topic per paragraph.

• Use simple subject-verb-object order. Avoid nested clauses.
• Replace jargon with plain language unless the term is standard for the audience.
• Define acronyms on first use. Do not assume the reader knows internal project names.
• Use active voice: "The scheduler retries failed tasks" not "Failed tasks are retried by the scheduler."

Precision

Be exact about behavior, not suggestive.

• Write "Returns a list of strings" not "Returns some data."
• Write "Throws ValueError if the input is negative" not "May throw an error for bad input."
• Write "Timeout is 30 seconds" not "Timeout is fairly short."
• Distinguish "must" (requirement), "should" (recommendation), and "may" (optional).

Structure

Documents follow a predictable hierarchy:

• What this is (one sentence).
• What problem it solves (one paragraph).
• How to use it (minimal working example).
• Configuration or parameters (table or list with types and defaults).
• Error handling and edge cases.
• Limitations and assumptions.
• Links to related docs or source code. Do not bury the example under three paragraphs of motivation.

Code-Examples

Every concept must have a minimal reproducible example.

• Show the simplest possible call that produces a valid result.
• Show one error case if the failure mode is non-obvious.
• Include expected output as a comment or separate block.
• Keep examples copy-pasteable. No pseudocode in API docs.

Cross-References

Never leave the reader hunting for related information.

• Link to prerequisite concepts before using them.
• Link to deeper dives from high-level summaries.
• If a term is defined elsewhere, link the first use in each major section.
• Keep links working. Broken links erode trust faster than missing links.

Revision-Checklist

Before marking a doc complete:

• Can a new reader follow the example without asking for help?
• Are all claims verifiable (traceable to code, test, or source)?
• Are there any ambiguous pronouns ("it", "this") that could mislead?
• Is every number, parameter, and default current with the code?
• Does the doc answer "what happens if this goes wrong?"