7.1 KiB
Pattern: Progressive Disclosure
Status: ✅ Validated (2 uses) Domain: Documentation Transferability: Universal (applies to all complex topics)
Problem
Complex technical topics overwhelm readers when presented all at once. Users with different expertise levels need different depths of information.
Symptoms:
- New users bounce off documentation (too complex)
- Dense paragraphs with no entry point
- No clear path from beginner to advanced
- Examples too complex for first-time users
Solution
Structure content in layers, revealing complexity incrementally:
- Simple overview first - What is it? Why care?
- Quick start - Minimal viable example (10 minutes)
- Core concepts - Key ideas with simple explanations
- Detailed workflow - Step-by-step with all options
- Advanced topics - Edge cases, optimization, internals
Key Principle: Each layer is independently useful. Reader can stop at any level and have learned something valuable.
Implementation
Structure Template
# Topic Name
**Brief one-liner** - Core value proposition
---
## Quick Start (10 minutes)
Minimal example that works:
- 3-5 steps maximum
- No configuration options
- One happy path
- Working result
---
## What is [Topic]?
Simple explanation:
- Analogy or metaphor
- Core problem it solves
- Key benefit (one sentence)
---
## Core Concepts
Key ideas (3-6 concepts):
- Concept 1: Simple definition + example
- Concept 2: Simple definition + example
- ...
---
## Detailed Guide
Complete reference:
- All options
- Configuration
- Edge cases
- Advanced usage
---
## Reference
Technical details:
- API reference
- Configuration reference
- Troubleshooting
Writing Guidelines
Layer 1 (Quick Start):
- ✅ One path, no branches
- ✅ Copy-paste ready code
- ✅ Working in < 10 minutes
- ❌ No "depending on your setup" qualifiers
- ❌ No advanced options
Layer 2 (Core Concepts):
- ✅ Explain "why" not just "what"
- ✅ One concept per subsection
- ✅ Concrete example for each concept
- ❌ No forward references to advanced topics
- ❌ No API details (save for reference)
Layer 3 (Detailed Guide):
- ✅ All options documented
- ✅ Decision trees for choices
- ✅ Links to reference for details
- ✅ Examples for common scenarios
Layer 4 (Reference):
- ✅ Complete API coverage
- ✅ Alphabetical or categorical organization
- ✅ Brief descriptions (link to guide for concepts)
When to Use
✅ Use progressive disclosure when:
- Topic has multiple levels of complexity
- Audience spans from beginners to experts
- Quick start path exists (< 10 min viable example)
- Advanced features are optional, not required
❌ Don't use when:
- Topic is inherently simple (< 5 concepts)
- No quick start path (all concepts required)
- Audience is uniformly expert or beginner
Validation
First Use: BAIME Usage Guide
Context: Explaining BAIME framework (complex: iterations, agents, capabilities, value functions)
Structure:
- What is BAIME? (1 paragraph overview)
- Quick Start (4 steps, 10 minutes)
- Core Concepts (6 concepts explained simply)
- Step-by-Step Workflow (detailed 3-phase guide)
- Specialized Agents (advanced topic)
Evidence of Success:
- ✅ Clear entry point for new users
- ✅ Each layer independently useful
- ✅ Complexity introduced incrementally
- ✅ No user feedback yet (baseline), but structure feels right
Effectiveness: Unknown (no user testing yet), but pattern emerged naturally from managing complexity
Second Use: Iteration-1-strategy.md (This Document)
Context: Explaining iteration 1 strategy
Structure:
- Objectives (what we're doing)
- Strategy Decisions (priorities)
- Execution Plan (detailed steps)
- Expected Outcomes (results)
Evidence of Success:
- ✅ Quick scan gives overview (Objectives)
- ✅ Can stop after Strategy Decisions and understand plan
- ✅ Execution Plan provides full detail for implementers
Effectiveness: Pattern naturally applied. Confirms reusability.
Variations
Variation 1: Tutorial vs Reference
Tutorial: Progressive disclosure with narrative flow Reference: Progressive disclosure with random access (clear sections, can jump anywhere)
Variation 2: Depth vs Breadth
Depth-first: Deep dive on one topic before moving to next (better for learning) Breadth-first: Overview of all topics before deep dive (better for scanning)
Recommendation: Breadth-first for frameworks, depth-first for specific features
Related Patterns
- Example-Driven Explanation: Each layer should have examples (complements progressive disclosure)
- Multi-Level Content: Similar concept, focuses on parallel tracks (novice vs expert)
- Visual Structure: Helps users navigate between layers (use clear headings, TOC)
Anti-Patterns
❌ Hiding required information in advanced sections
- If it's required, it belongs in core concepts or earlier
❌ Making quick start too complex
- Quick start should work in < 10 min, no exceptions
❌ Assuming readers will read sequentially
- Each layer should be useful independently
- Use cross-references liberally
❌ No clear boundaries between layers
- Use headings, whitespace, visual cues to separate layers
Measurement
Effectiveness Metrics
- Time to first success: Users should get working example in < 10 min
- Completion rate: % users who finish quick start (target: > 80%)
- Drop-off points: Where do users stop reading? (reveals layer effectiveness)
- Advanced feature adoption: % users who reach Layer 3+ (target: 20-30%)
Quality Metrics
- Layer independence: Can each layer stand alone? (manual review)
- Concept density: Concepts per layer (target: < 7 per layer)
- Example coverage: Does each layer have examples? (target: 100%)
Template Application Guidance
Step 1: Identify Complexity Levels
Map your content to layers:
- What's the simplest path? (Quick Start)
- What concepts are essential? (Core Concepts)
- What options exist? (Detailed Guide)
- What's for experts only? (Reference)
Step 2: Write Quick Start First
This validates you have a simple path:
- If quick start is > 10 steps, topic may be too complex
- If no quick start possible, reconsider structure
Step 3: Expand Incrementally
Add layers from simple to complex:
- Core concepts next (builds on quick start)
- Detailed guide (expands core concepts)
- Reference (all remaining details)
Step 4: Test Transitions
Verify each layer works independently:
- Can reader stop after quick start and have working knowledge?
- Does core concepts add value beyond quick start?
- Can reader skip to reference if already familiar?
Status
Validation: ✅ 2 uses (BAIME guide, Iteration 1 strategy) Confidence: High - Pattern emerged naturally twice Transferability: Universal (applies to all complex documentation) Recommendation: Extract to template (done in this iteration)
Next Steps:
- Validate in third context (different domain - API docs, troubleshooting guide, etc.)
- Gather user feedback on effectiveness
- Refine metrics based on actual usage data