223 lines
7.6 KiB
Markdown
223 lines
7.6 KiB
Markdown
# Exemplary Documentation Projects
|
|
|
|
This reference document synthesizes research on projects widely recognized for exceptional documentation quality.
|
|
|
|
## Framework Documentation
|
|
|
|
### React (react.dev)
|
|
**Why Exceptional:**
|
|
- Prioritizes learning outcomes over comprehensive coverage
|
|
- Interactive sandboxes reduce friction
|
|
- Progressive complexity with clear learning paths
|
|
- Removed gatekeeping; accessible to newcomers
|
|
|
|
**Key Patterns:**
|
|
- Learning path architecture (Get Started → Learn → Reference)
|
|
- Conversational tone, example-driven teaching
|
|
- "Try it out" sections encourage experimentation
|
|
- Progressive disclosure: simple examples first, edge cases later
|
|
- Each section includes "What's Next?" guidance
|
|
|
|
**Notable Examples:**
|
|
- useState Hook Documentation: Opens with 3-line working example
|
|
- Tic-tac-toe Tutorial: Complete interactive app built step-by-step
|
|
- Dual presentation pathways: Quick answers + deep dives
|
|
|
|
---
|
|
|
|
### Rust Documentation
|
|
**Why Exceptional:**
|
|
- Built-in documentation testing (`cargo test --doc`)
|
|
- Comprehensive philosophy: "if public, must be documented"
|
|
- Tooling integration standardizes quality across ecosystem
|
|
- Community RFC-based conventions ensure consistency
|
|
|
|
**Key Patterns:**
|
|
- Standard structure: summary → explanation → examples → errors → panics
|
|
- All code examples compile and execute as tests
|
|
- Smart boilerplate hiding with `#` prefix
|
|
- Explicit documentation of failure modes
|
|
|
|
**Notable Examples:**
|
|
- Vec<T> Documentation: Multiple usage examples, guarantees section
|
|
- Result Documentation: Pattern matching, error propagation patterns
|
|
- Tested examples guarantee correctness
|
|
|
|
---
|
|
|
|
### Django Documentation
|
|
**Why Exceptional:**
|
|
- Learn-by-doing philosophy with real projects
|
|
- Multiple learning pathways (tutorials, topic guides, reference, how-tos)
|
|
- Comprehensive coverage from intro to production
|
|
- Progressive revelation of complexity
|
|
|
|
**Key Patterns:**
|
|
- Tutorials take you "by the hand" through concrete projects
|
|
- Show directory structure visually
|
|
- Platform-specific variants (Windows vs. Linux)
|
|
- Explain reasoning: "why does Django work this way?"
|
|
- Anticipate common problems
|
|
|
|
**Notable Examples:**
|
|
- "Writing your first Django app" tutorial: 7-part narrative building on previous parts
|
|
- Multi-part tutorials create continuity and momentum
|
|
- Admin interface-first teaching builds early confidence
|
|
|
|
---
|
|
|
|
### Vue.js Documentation
|
|
**Why Exceptional:**
|
|
- Flexibility recognition: presents multiple API approaches equally
|
|
- Multiple entry points for different learning styles
|
|
- Clear prerequisites stated upfront
|
|
- Progressive framework philosophy reflected in docs
|
|
|
|
**Key Patterns:**
|
|
- Dual API presentation (Options vs. Composition)
|
|
- Multiple learning paths: "Try it" vs. "Read Guide" vs. "Examples"
|
|
- Visual SFC (Single File Component) structure diagrams
|
|
- Progressive disclosure: scales from simple to advanced
|
|
- "Try in Playground" links for hands-on learning
|
|
|
|
**Notable Examples:**
|
|
- Reactivity Fundamentals: Side-by-side API comparison
|
|
- Component Basics: Progressive complexity (template → props → events)
|
|
- Prerequisites stated clearly: "assumes basic HTML, CSS, JS familiarity"
|
|
|
|
---
|
|
|
|
## Developer Tools & Platforms
|
|
|
|
### Stripe
|
|
**Why Exceptional:**
|
|
- Industry gold standard for API documentation
|
|
- "Don't overdo it" philosophy: elegant simplicity
|
|
- Balances comprehensiveness with navigability
|
|
- Assumes developer intelligence
|
|
|
|
**Key Patterns:**
|
|
- Two-panel layout (explanation + code side-by-side)
|
|
- Clean aesthetic with whitespace
|
|
- Single-page format with anchor navigation
|
|
- Multi-language code samples inline
|
|
- Robust search functionality
|
|
- Seamless topic linking
|
|
|
|
**Notable Examples:**
|
|
- Quickstart Guide: Multiple languages inline, progressive complexity
|
|
- Error Handling: Transforms errors into actionable guidance
|
|
- API Reference: Clear request/response examples
|
|
|
|
---
|
|
|
|
### Twilio
|
|
**Why Exceptional:**
|
|
- Gold standard for intuitive structure
|
|
- Makes complex concepts accessible
|
|
- Supports multiple programming languages seamlessly
|
|
- Use case-driven organization
|
|
|
|
**Key Patterns:**
|
|
- Two-panel layout with multi-language samples
|
|
- Beginner-friendly explainers ("What's a REST API, anyway?")
|
|
- Progressive learning paths for varying experience
|
|
- Practical tutorials with screenshots
|
|
- Language selector at top of every page
|
|
- Copy-paste ready code
|
|
|
|
**Notable Examples:**
|
|
- Quickstart Guides: Simple actionable steps with screenshots
|
|
- Webhooks Documentation: Explains concept before technical details
|
|
- Customer story integration: Real examples demonstrate value
|
|
|
|
---
|
|
|
|
### Slack
|
|
**Why Exceptional:**
|
|
- Balances simplicity with depth
|
|
- Plain language without dumbing down
|
|
- Difficulty indicators help self-assessment
|
|
- Accessible to junior devs, comprehensive for advanced
|
|
|
|
**Key Patterns:**
|
|
- Difficulty labels (beginner/intermediate/advanced)
|
|
- Plain language and everyday vocabulary
|
|
- Clear "next steps" guidance
|
|
- Example-driven explanations
|
|
- Concept-first teaching ("why" before "how")
|
|
|
|
**Notable Examples:**
|
|
- Getting Started Guide: Clear progression from basics
|
|
- Interactive App Tutorials: Real-world scenarios
|
|
- Events API: Complex concepts in accessible language
|
|
|
|
---
|
|
|
|
### Vercel
|
|
**Why Exceptional:**
|
|
- Integrated examples repository
|
|
- Template-driven learning
|
|
- TypeScript-first documentation
|
|
- Multiple learning formats
|
|
|
|
**Key Patterns:**
|
|
- Examples repository as documentation
|
|
- Template ecosystem for common use cases
|
|
- Progressive complexity (hello-world to sophisticated)
|
|
- Visual workflow diagrams
|
|
- Links to runnable GitHub repos
|
|
- Changelog-driven updates
|
|
|
|
**Notable Examples:**
|
|
- Deployment Documentation: Links to working example repos
|
|
- Edge Functions Guide: TypeScript types + runnable examples
|
|
- Open-source template library
|
|
|
|
---
|
|
|
|
## Universal Success Patterns
|
|
|
|
### Structural Patterns
|
|
1. **Two-panel or multi-column layout** - Code alongside explanations
|
|
2. **Clear navigation** - Persistent sidebars or top navigation
|
|
3. **Getting Started sections** - Quick wins before comprehensive coverage
|
|
4. **Progressive disclosure** - Basic concepts first, advanced clearly marked
|
|
5. **Multiple learning pathways** - Tutorials, guides, reference, how-tos
|
|
|
|
### Content Patterns
|
|
1. **Example-driven teaching** - Show before explaining
|
|
2. **Multi-language support** - Code in 3-5+ languages
|
|
3. **Real use cases** - Show what you can build
|
|
4. **Error documentation** - Comprehensive error guides
|
|
5. **Copy-paste readiness** - Code works immediately
|
|
|
|
### Writing Style
|
|
1. **Conversational but professional** - Accessible without being casual
|
|
2. **Active voice** - "Create an API key" not "An API key can be created"
|
|
3. **Short sentences and paragraphs** - Digestible chunks
|
|
4. **Task-oriented structure** - Organized around what users want to accomplish
|
|
5. **Minimal jargon** - Define technical terms when necessary
|
|
6. **Examples before concepts** - Show first, explain second
|
|
|
|
### Quality Markers
|
|
1. **Respect for user time** - Clear "why this matters" upfront
|
|
2. **Assumption of competency** - Don't over-explain basics
|
|
3. **Practical focus** - Real-world over theoretical
|
|
4. **Multiple learning styles** - Reading, code, visuals, examples
|
|
5. **Regular maintenance** - Changelogs show active updates
|
|
6. **Feedback mechanisms** - Ways to report issues
|
|
|
|
## Common Anti-Patterns to Avoid
|
|
|
|
1. **Abstract explanations before examples** - Show, then explain
|
|
2. **Alphabetical API organization** - Hard to discover patterns
|
|
3. **Outdated examples** - Damages credibility
|
|
4. **Unstated prerequisites** - Readers get lost
|
|
5. **Dense paragraphs** - Cognitive overload
|
|
6. **Separating "why" from "how"** - Context matters
|
|
7. **Jargon without definition** - Excludes learners
|
|
8. **Missing error documentation** - Users struggle to debug
|
|
9. **Inconsistent terminology** - Creates confusion
|
|
10. **No visual hierarchy** - Hard to scan
|