RahulRachhoya Writing Docs
Principles
- Know your audience — end users need different docs than API consumers
- Show, don't just tell — every concept needs an example
- Keep it concise — every sentence should earn its place
- Structure for scanning — headings, lists, code blocks, and tables
- 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!)