Initial commit

skills/writing-documentation/references/exemplary-projects.md

@@ -0,0 +1,222 @@
+# 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