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.
Core Philosophy
| Principle | Meaning | |-----------|---------| | Code is the star | Prose exists to introduce, contextualize, and connect code examples | | Scannable over narrative | Readers skim for answers; structure for rapid lookup | | Show, don't tell | Diff annotations and working examples beat explanations | | One concept per step | Never introduce multiple ideas simultaneously | | Full files, not snippets | Every code block should be runnable in isolation | | Template rigidly | Predictable structure is a feature, not a limitation |
Quick Reference: Critical Rules
| Category | DO | DON'T |
|----------|-----|-------|
| Voice | "you" for concepts, "we" for tutorials | Passive voice |
| Tone | Professional-casual, confident | Humorous, condescending, or stiff |
| Sentences | 10-25 words, active voice | 35+ word run-on sentences |
| Code examples | Complete runnable files with focus annotations | Partial snippets missing context |
| Parameters | One ### heading per param with full example | Tables or lists of parameters |
| Optional params | Indicate via \| undefined in type | "Optional" badges or markers |
| Jargon | SDK-specific terms explained; ecosystem terms assumed | Over-explaining industry basics |
| Sections | Rigid ordering: Import → Usage → Parameters → Return Type | Freeform section ordering |
| Cross-refs | Link to related APIs inline and in dedicated sections | "See also" dump at bottom |
| Warnings | Use a warning admonition for critical info (see your framework's syntax) | Inline bold warnings in prose |
Detailed Guidance by Topic
- Documentation structure: See references/structure.md for site architecture, page templates, navigation, shared content systems
- Narrative tone & explanation pages: See references/tone.md for voice, style, sentence patterns, jargon handling, and explanation/concept page guidance
- Tutorials & how-to guides: See references/guides.md for tutorial rules (learning-oriented), how-to guide rules (task-oriented), progressive disclosure, framework variants
- API references: See references/api-reference.md for parameter docs, return types, TypeScript presentation, cross-referencing
- VitePress setup: See references/vitepress.md for project init, config, markdown extensions, twoslash, code groups, shared includes
- GitBook setup: See references/gitbook.md for Git Sync, content blocks, steppers, OpenAPI integration, reusable content