# Writing Docs

> Write clear, scannable documentation — explain the why, use examples, and keep it concise.

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

---


# Writing Docs

## Principles
1. **Know your audience** — end users need different docs than API consumers
2. **Show, don't just tell** — every concept needs an example
3. **Keep it concise** — every sentence should earn its place
4. **Structure for scanning** — headings, lists, code blocks, and tables
5. **Explain the why** — what problem this solves, not just how to use it

## Structure
- **Quickstart** — get running in 5 minutes with copy-paste commands
- **Concepts** — explain the mental model, terminology
- **How-to guides** — task-oriented, step-by-step
- **Reference** — exhaustive API docs, auto-generated
- **Troubleshooting** — common problems and solutions

## Style Rules
- Active voice ("the API returns..." not "it is returned by the API")
- Present tense ("this tool creates..." not "this tool will create")
- Consistent terminology (don't switch between "query" and "search")
- Use second person ("you can install..." not "users can install")
- Code examples are always runnable (test them!)