Table of Contents
- Act I: The Knowledge Trap
- Act II: The Multiplication Trap
- Act III: Designing the Accordion Document
- Implementation: Progressive Disclosure in Practice
- Real-World Example: Before and After
- Epilogue: Knowledge Preserved, Cognitive Load Reduced
Chapter 8: The Accordion Document #
Blue Gopher scrolled through the runbook one last time.
It had everything: deployment steps, rollback commands, KPI targets, control logs, stakeholder notes. Every section was polished.
And yet, when the P0 incident hit last week, engineers spent 20 minutes hunting for the rollback command buried under executive KPI analysis.
"Where's the actual command?" "Why am I reading about risk mitigation again?" "This feels like drinking from a fire hose."
They were right. His Deploy Feature X runbook contained everything he knew about the deployment—but that complete knowledge overwhelmed every reader. Nobody could find their entry point into his thinking.
Act I: The Knowledge Trap #
During sprint sync, Blue faced the same pattern across three different scenarios:
- Executives skimmed for KPIs, got lost in terminal commands.
- Engineers scrolled past strategy blurbs to find the steps.
- Auditors hunted for approvals buried in implementation details.
That night, Blue sat alone with his markdown file, realizing the fundamental problem: he was trying to think and communicate in the same breath.
His runbook was perfect for capturing knowledge. Terrible for consuming it.
Act II: The Multiplication Trap #
Le Auditor arrived, peering over his wire-rimmed glasses.
"You need audience separation. Write three different documents."
Blue tried the obvious fix—splitting his runbook into exec-summary.md, engineer-steps.md, and audit-log.md.
It got worse.
Within two weeks, the engineer document was three versions behind. The executive summary referenced outdated KPIs. The audit log was missing the latest control updates.
"This isn't separation," Le Auditor said, reviewing the chaos. "It's documentation debt."
Blue stared at his file tree: four documents, three outdated, zero trust.
Act III: Designing the Accordion Document #
Scout-nut scurried up with a different approach.
"What if you write to capture your thinking, then design for their consumption?"
Together, they defined a new protocol:
Step 1: Brain Dump Everything
Orb would draft one complete runbook with all the context, decisions, alternatives, and edge cases. No audience optimization. Pure knowledge capture.
Step 2: Design Progressive Entry Points
Instead of splitting documents, create consumption layers in the same file:
1# Deployment Runbook
2
3## TL;DR (30 seconds)
4- Command: `terraform apply -var-file=prod.tfvars`
5- Success: FunnelDash latency drops 40%
6- Rollback: `terraform destroy` if errors
7
8<details>
9<summary>📋 Full Context & Decision History</summary>
10
11[Complete thinking here: why this approach, what we considered,
12what we rejected, edge cases, assumptions...]
13</details>
14
15<details>
16<summary>✅ Compliance & Controls</summary>
17
18[Approvals, change logs, control verification...]
19</details>
Step 3: Test Entry Points
Each consumption layer gets validated:
- Can executives get KPIs in 30 seconds?
- Can engineers copy-paste commands without scrolling?
- Can auditors find all controls without reading implementation?
Implementation: Progressive Disclosure in Practice #
1. Start with Complete Thinking Write everything you know. Context, decisions, alternatives, edge cases. Optimize for knowledge capture, not readability.
2. Design Consumption Layers Create clear entry points using collapsible sections:
1<!-- Quick Start (30 seconds) -->
2## TL;DR
3Essential actions only
4
5<!-- Context (5 minutes) -->
6<details><summary>📋 Why & How</summary>
7Background, decisions, rationale
8</details>
9
10<!-- Deep Dive (15+ minutes) -->
11<details><summary>🔍 Complete Details</summary>
12Edge cases, alternatives, troubleshooting
13</details>
14
15<!-- Compliance (as needed) -->
16<details><summary>✅ Audit Trail</summary>
17Controls, approvals, change history
18</details>
3. Use Tool-Based Views When Possible
- Notion: Database views with filters
- Obsidian: Tag-based queries
- GitBook: Conditional content blocks
- Confluence: Page layouts with audience toggles
4. Test Cognitive Load Each layer should pass the consumption test:
- 30-second scan: Core actions visible
- 5-minute read: Context without overwhelm
- Deep dive: Complete thinking preserved
Real-World Example: Before and After #
Before: Linear Overload
1# Deployment Guide
2Risk assessment shows 3% failure rate based on...
3[2000 words of context]
4...finally, run: terraform apply
After: Progressive Disclosure
1# Deployment Guide
2
3## Quick Start
4`terraform apply -var-file=prod.tfvars`
5
6<details><summary>📋 Context & Risk Analysis</summary>
7Risk assessment shows 3% failure rate...
8[Complete analysis here]
9</details>
Result: Engineers get commands in 5 seconds. Executives can drill into risk data when needed. Same information, better consumption experience.
Epilogue: Knowledge Preserved, Cognitive Load Reduced #
Blue posted one link in the channel:
The replies came in fast:
- "Found the command immediately."
- "Great context in the details section."
- "Finally, compliance info that's organized."
Scout-nut nodded approvingly.
"One source of truth. Multiple ways to consume it."
Le Auditor adjusted his glasses, satisfied.
"Knowledge architecture. Not document proliferation."
Blue smiled, closing his laptop. One runbook. Complete thinking. Progressive consumption.
Finally, documentation that worked with human attention spans instead of against them.
🎯 Takeaway: The Accordion Document
Separate knowledge capture from knowledge consumption. Write one complete document to preserve your thinking, then design progressive entry points using collapsible sections. This maintains your complete mental model while reducing cognitive load through structured disclosure. Test each consumption layer against time-based usage patterns: 30-second scan, 5-minute context, deep-dive research.