documentation-writing
SKILL.md
This skill guides the creation of authoritative, user-centric technical documentation. Produce content that is not merely informational but is an engineered product in itself—optimized for clarity, scannability, and utility.
The user provides documentation requirements: a README, an architectural overview, an API guide, or inline comments. They may include context about the target audience (developers, stakeholders) or the complexity of the feature.
Documentation Strategy
Before writing, establish the context and commit to a USER-FIRST strategy:
- Audience: Who is reading this? (Junior Developers, DevOps Engineers, CTOs). Adjust technical depth accordingly.
- Objective: What is the specific "Job to be Done"? (e.g., "Deploy in 5 minutes," "Debug a specific error," "Understand the data model").
- Voice: authoritative yet accessible. Professional, direct, and concise. Avoid academic jargon; prefer clear, actionable language found in documentation from industry leaders like Stripe, Vercel, or Linear.
- Value: Why does this document exist? It must reduce cognitive load, not add to it.
CRITICAL: Every sentence must earn its place. If it does not clarify a concept or guide an action, remove it. Clarity is the ultimate metric of success.
Then implement documentation that is:
- Structurally Sound: Logical hierarchy with clear navigation.
- Action-Oriented: Focus on what the user needs to do.
- Single Source of Truth: Aligned strictly with the code and official platform behaviors.
- Visually Scannable: Heavy use of formatting tools to break up text.