Information architecture
Four page types that keep a documentation site navigable as it grows.
1 min read
Docs fail when a reader can't tell where to look. The fix is a small set of page types with clear jobs. We use the Diátaxis model.
The four page types#
| Type | Reader's need | Written as | Example |
|---|---|---|---|
| Tutorial | "I'm new. Teach me." | A guided lesson with a guaranteed outcome | Build your first integration |
| How-to guide | "I need to do X." | Steps for one real-world task | Rotate an API key |
| Reference | "What exactly is X?" | Complete, factual, consistent | POST /v1/projects |
| Explanation | "Why does it work this way?" | Background and design reasoning | How rate limiting works |
Build the navigation#
Start with tasks#
Group navigation by what readers want to do, not by your org chart or internal feature names.
Keep it shallow#
Two levels of navigation cover most products. If you need a third, split the site by product or audience.
Make search first-class#
Search is the primary navigation for experienced users. Index titles, headings and body text, and log the queries that return nothing. That list is your next backlog.
Run a content audit#
Before you restructure, inventory what exists:
- Export every URL with traffic, last-updated date and owner.
- Mark each page as keep, merge, rewrite or retire.
- Map the survivors onto the four page types.
- Write redirects for everything you move.
url,views_90d,last_updated,type,action
/docs/webhooks,4820,2025-02-11,how-to,rewrite
/docs/webhooks-v1,310,2023-06-30,reference,retireWas this page helpful?