---
name: technical-writing-clarity
description: Use this skill when writing documentation, READMEs, technical specs, runbooks, or any text that explains a system or process to other engineers. Apply before writing any developer-facing document.
category: communication
---

# Technical Writing for Clarity

**Principles:**
- **Lead with the purpose:** What is this document for and who is it for?
- **One idea per paragraph.** Long paragraphs hide key information.
- **Use active voice:** `Run the script` not `The script should be run`.
- **Concrete over abstract:** Show an example rather than describing it abstractly.
- **Avoid jargon** you have not defined unless the audience definitely knows it.

**Structure for runbooks/how-tos:**
1. Overview (1–2 sentences)
2. Prerequisites
3. Steps (numbered, imperative)
4. Verification / expected output
5. Troubleshooting

**Anti-patterns:** Documenting `what` without `why`, outdated examples, walls of text without headers.