sdk-documentation
Installation
SKILL.md
SDK Documentation Best Practices
Rules for writing clear, scannable, code-forward documentation for public SDKs. Derived from analysis of best-in-class SDK documentation (wagmi, viem, TanStack). Rules are domain-agnostic; examples use generic SDK patterns with occasional web3 illustrations.
Documentation Type Router
Before writing, identify which type of page you're creating. Each type has different rules.
| Question you're answering | Doc type | Template | Key rule |
|---|---|---|---|
| "Help me learn this SDK" | Tutorial (Getting Started) | guides.md → Tutorials | Learning-oriented: guide the reader, eliminate choices, show destination early |
| "Help me accomplish X" | How-to Guide (Task Guide) | guides.md → How-to Guides | Task-oriented: assume competence, action-only, address real-world complexity |
| "What does X do / accept / return?" | API Reference | api-reference.md | Information-oriented: describe only, zero explanation, mirror product structure |
| "Why does X work this way?" | Explanation (Concept/Why page) | tone.md → Explanation Pages | Understanding-oriented: provide context, make connections, admit tradeoffs |
The cardinal sin is mixing types. A tutorial that stops to explain architecture loses the learner. A reference page that teaches loses the practitioner looking up a parameter. An explanation page that includes step-by-step instructions belongs in a how-to guide.