Documentation
Progressive Disclosure: Structuring Information
Project-Agent-trust-merge / engineer-docs/best-practices/progressive-disclosure.md
What Is Progressive Disclosure?
Progressive disclosure means presenting information in layers, starting with basics and adding complexity only when needed.
Think of it like a video game tutorial:
- Level 1: Teach ONE basic skill
- Level 2: Introduce a second mechanic
- Level 3: Combine both in a challenge
- Advanced: Explain all the edge cases and optimizations
Your documentation should work the same way.
---
The Documentation Stack: Layers of Detail
`` ┌─────────────────────────────────────┐ │ README │ "What is this?" │ - One sentence │ │ - Copy-paste setup │ │ - Links to everything │ └─────────────────────────────────────┘ ↓ ┌─────────────────────────────────────┐ │ QUICK_START │ "How do I run it?" │ - 5 minute tutorial │ │ - One success path │ │ - Minimal setup │ └─────────────────────────────────────┘ ↓ ┌─────────────────────────────────────┐ │ API_REFERENCE │ "What can I do?" │ - Every method documented │ │ - Complete parameter list │ │ - All error cases │ └─────────────────────────────────────┘ ↓ ┌─────────────────────────────────────┐ │ ARCHITECTURE │ "How does it work?" │ - System design │ │ - Data flow diagrams │ │ - Design decisions │ └─────────────────────────────────────┘ ↓ ┌─────────────────────────────────────┐ │ GUIDES & EXAMPLES │ "How do I...?" │ - Feature-specific tutorials │ │ - Real-world examples │ │ - Common patterns │ └─────────────────────────────────────┘ ``
Key principle: Each layer assumes knowledge from the layer above it.
---
How to Apply Progressive Disclosure
1. README — The Orientation Layer
```markdown
My Project
One sentence describing what it does.
Quick Start
``bash npm install npm run dev ``
What's This For?
[3-4 sentences with links to deeper docs]
Documentation
```
Assumption: Reader knows nothing about your project. Goal: Get them to Quick Start or help them decide if they care.
---
2. Quick Start — The "Hello World" Layer
```markdown
Quick Start
Prerequisites
- [List anything they need to know]
Installation
[Exact commands; no explanations]
Your First Program
[Copy-paste example; it works]
What's Next?
- [Link to API Reference]
- [Link to Guides]
```
Assumption: Reader wants to try it immediately. Goal: Working example in 5 minutes. No philosophy, no background.
---
3. API Reference — The Comprehensive Layer
```markdown
client.execute()
``python async def execute(connector: str, operation: str, params: dict) -> dict: ``
Description: [One sentence]
Parameters: | Name | Type | Description | |------|------|-------------| | connector | str | Which connector to use |
Returns: [What it gives back]
Raises: [What goes wrong]
Examples: ```python
Real code showing usage
`` ``
Assumption: Reader knows basic concepts. Goal: Complete reference they can scan.
---
4. Architecture — The "Why" Layer
```markdown
Architecture
System Design
[Diagram showing components]
Core Concepts
[Explain 3-5 key ideas]
Data Flow
[Show request → processing → response]
Design Decisions
| Decision | Why | Trade-offs | |----------|-----|-----------| | [Decision] | [Rationale] | [What we sacrificed] | ```
Assumption: Reader understands the API. Goal: Understand the design philosophy.
---
5. Guides & Examples — The "How Do I..." Layer
```markdown
How to [Accomplish Something]
Scenario
[What problem does this solve?]
Steps
- Do X [with code]
- Do Y [with code]
- Verify Z [with code]
Common Issues
- [Problem and solution]
```
Assumption: Reader knows API and concepts. Goal: Accomplish a specific task.
---
Why This Matters: The Knowledge Pyramid
`` ╱╲ ╱ ╲ Advanced (5% of users) ╱────╲ - Architecture deep dives ╱ ╲ - Performance optimization ╱────────╲ - Extension patterns ╱ ╲ ╱────────────╲ Competent (30% of users) ╱ ╲ - How-to guides ╱────────────────╲ - Advanced examples ╱ ╲ - API reference ╱──────────────────╲ Newcomers (65% of users) ``
Different users need different layers:
- 65% of people need Quick Start to get going (Layers 1-2)
- 30% of people will use API reference and guides (Layers 2-3)
- 5% of people care about architecture (Layer 4)
Progressive disclosure serves all of them without overwhelming anyone.
---
Anti-Pattern: The Wall of Text
DON'T do this:
```markdown
Complete Documentation
Our system uses a distributed architecture with eventual consistency and implements the CQRS pattern. Users can execute operations on connectors, which are filtered through our policy engine. The policy engine uses behavioral drift detection to identify anomalies... [15 pages of technical detail] ```
Why it fails: Someone just wants to install it. They see a wall of text and leave.
---
Anti-Pattern: Too Many Layers
DON'T do this either:
```
- README
- README (short)
- README (long)
- Overview
- Introduction
- Getting Started (for Linux)
- Getting Started (for Mac)
- Getting Started (for Windows)
- Advanced Getting Started
- API Concepts
- API Reference Part 1
- API Reference Part 2
... ```
Why it fails: Too much choice. People don't know which to read.
---
Checklist: Applying Progressive Disclosure
- [ ] README answers "What is this?" in one sentence
- [ ] Quick Start gets someone running in 5 minutes
- [ ] API Reference is complete (all methods, all parameters)
- [ ] Architecture explains system design (not how to use it)
- [ ] Guides solve specific, real problems
- [ ] Each layer links to the next layer
- [ ] Each layer assumes knowledge from previous layers
- [ ] No layer tries to do 2+ things at once
---
Summary
Progressive disclosure works because:
- Newcomers don't get lost in advanced topics
- Experienced users can jump to what they need (API Reference, Architecture)
- Everyone finds their level without searching
- Documentation stays focused — each page has one purpose
The result? Users find what they need faster and understand it better.