Technical Writing

Technical Writing

Workflow for clear, accurate, maintainable developer documentation. Write for a specific reader and a specific goal; cut everything that does not serve it.

When to use

• Creating or rewriting a README.
• Documenting an API, SDK, or endpoint.
• Writing an architecture decision record (ADR) or design doc.
• Producing tutorials, how-to guides, or onboarding docs.
• Drafting changelogs / release notes.

Engineering standards (apply to every task)

• Languages. When the docs include code, use the project's actual language and idioms — TypeScript/JavaScript, Python, Go, Java, C#, Rust, Kotlin, Ruby, PHP and others. Tag every code block with its language and make it runnable as written.
• Document why, not what. Explain intent, contracts, and how to use the thing. Do NOT narrate code line-by-line or duplicate what a signature already states.
• Clean structure. One idea per section; consistent terminology; prefer lists and tables over walls of text; no duplication across pages.
• Hygiene. No filler ("simply", "just", "obviously"). No generic or decorative emojis unless the user explicitly asks. Match the project's existing docs style and tone. Reply in the user's language unless the project documents in another language by convention.

Core principles

1. Audience and goal first. State who the reader is and what they should be able to do after reading. Match depth to that reader.
2. Lead with the answer. Put the most important info (what it is, how to run it) at the top. Details and edge cases come after.
3. Show, then tell. Every concept gets a concrete, copy-pasteable example. Examples must actually work.
4. Accurate over comprehensive. Wrong docs are worse than missing docs. Only document what you've verified.
5. Keep it close to the code. Docs that live next to and change with the code stay true; orphaned docs rot.

README structure

1. One-sentence description of what it is and who it's for.
2. Quick start: install + minimal working example (the "30-second success").
3. Key features / capabilities.
4. Configuration and common options.
5. Usage examples for the main flows.
6. Links to deeper docs, contributing, license.

API documentation checklist

• Every endpoint/function: purpose, parameters (type, required, default), return shape, errors.
• A realistic request and response example for each.
• Auth requirements stated explicitly.
• Edge cases, rate limits, and idempotency noted.
• Versioning and deprecation clearly marked.

ADR / design doc checklist

• Context: the problem and constraints.
• Options considered, with trade-offs.
• Decision and its rationale.
• Consequences (what becomes easier/harder).
• Status (proposed / accepted / superseded) and date.

Style checklist

• Active voice, present tense, second person ("you run", not "the user should run").
• Short sentences; one idea each. Prefer lists and tables to walls of text.
• Define jargon on first use or link to it.
• Consistent terminology — don't call the same thing three names.
• Code blocks are tagged with the language and are runnable as written.
• No filler ("simply", "just", "obviously") that hides real difficulty.

Anti-patterns to flag

• Docs that explain what the code does line-by-line instead of why and how to use it.
• Out-of-date examples that no longer run.
• A README that starts with history/motivation instead of how to use the thing.
• Undefined acronyms and assumed context.
• Screenshots of code/text instead of copy-pasteable blocks.

Output expectations

Deliver finished, ready-to-commit Markdown. When improving existing docs, preserve correct content and explain what you changed and why. Always write in the user's language unless the project's docs use another language by convention.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: santim025
• Source: santim025/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.