# Technical Writing Clarity

> 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.

- Skill: `gabrielmoreira/technical-writing-clarity` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gabrielmoreira/technical-writing-clarity`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gabrielmoreira/technical-writing-clarity/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: gabrielmoreira (https://skillmd.com/u/gabrielmoreira)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/gabrielmoreira/technical-writing-clarity

---


# 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.