ExplainIt
How to write explainer pages that don't overwhelm
Lead with the answer, not the journey.
Users come with a question. Answer it immediately. Details come later, on demand.
Structure
1. The Hook (above the fold)
- One sentence explaining what this is
- The key insight - the single most important thing to understand
- Optional: a simple visual/diagram
No scrolling required to get the main point.
2. Progressive Disclosure
Use expandable sections for everything else. User clicks to expand only what they need.
3. Information Hierarchy
- What (1 sentence)
- Why it matters (collapsed)
- How it works (collapsed)
- Code examples (collapsed)
- Edge cases / advanced (collapsed)
Anti-patterns
- Walls of text
- Multiple h2 sections visible at once
- Code examples shown before the concept is explained
- Explaining the problem before the solution
- Tables with more than 4-5 rows visible
Good vs Bad Example
Bad
# Progress Bars
## The Problem
LLM operations are slow...
[3 paragraphs about the problem]
## History
Progress bars were invented...
[2 paragraphs of history]
## Our Solution
[Finally getting to the point]
Good
# Progress Bars
Animate based on estimated time, not completion events.
<details>
<summary>Why?</summary>
Chunk-based updates cause 10+ second gaps.
</details>
Testing Your Page
- Can someone get the main point without scrolling?
- Is everything below the fold in a collapsed section?
- Could a busy person scan this in 10 seconds and leave informed?