“Top-down” and “bottom-up” refer to two different ways of organizing and presenting technical documentation.
Top-Down Documentation
Start with the big picture → then drill into details.
How it flows:
- Overall concept / system overview
- Major components
- Subsystems
- Specific features
- Technical details (APIs, configuration, code examples, etc.)
When it’s useful:
- For new users who need context
- Teaching workflow or how the system is structured
- Onboarding and product introductions
Typical examples:
- Getting Started guides
- Architecture overviews
- Product manuals
- High-level diagrams → component details
- Metaphor: “Explain the forest first, then the trees.”
Buttom-Up Documentation
Start with the details → then assemble them into the big picture.
How it flows:
- Low-level components or features
- Technical specifics (functions, modules, commands)
- Show how pieces combine
- Present full workflows or system understanding
When it’s useful:
- For experienced users or developers
- API-first platforms
- Reference-driven learning
Typical examples:
- API references
- Code documentation
- CLI command manuals
Comparisson
| Perspective | Top-Down | Bottom-Up |
|---|---|---|
| Audience | Beginners & decision-makers | Developers & power users |
| Cognitive buildup | Concept → implementation | Implementation → concept |
| Navigation | Narrative flow | Reference-style |
| Strength | Orientation & clarity | Precision & completeness |
| Risk | Might feel vague at first | Can overwhelm with details |