John Lancaster
2.3 KiB
2.3 KiB
Discoverability and Information Architecture
Use this reference to design docs that are progressively discoverable from overview to implementation detail.
IA Model
Organize by user intent, then by product area.
Recommended top-level model:
- Learn (concepts, architecture, mental models)
- Do (task/how-to paths)
- Reference (API, config, command catalog)
- Troubleshoot (symptoms, diagnostics, fixes)
!!! info "IA references" - Diataxis framework - Divio documentation system
Progressive Discoverability Pattern
Layer 1: Section Overview
Each section starts with an index page containing:
- What this section is for
- Who should read it
- Common journeys
- Links to key tasks and references
Layer 2: Task or Concept Pages
Each page includes:
- 1-2 sentence purpose
- prerequisites
- internal links to references and next steps
Layer 3: Deep Reference
Keep deep details in dedicated reference pages and link to them from task pages when needed.
Navigation Design Rules
- Keep navigation labels user-facing and action-oriented.
- Avoid duplicate labels in separate branches.
- Place high-frequency tasks near the top.
- Keep section depth shallow where possible.
!!! info "Relevant Zensical configuration docs" - Navigation setup - Search setup - Header setup - Footer setup
Link Strategy
- Every deep page should have at least one inbound link from a higher-level index page.
- Add "See also" blocks for neighboring tasks.
- Link to source-of-truth reference pages instead of duplicating config tables.
Search Optimization for Docs
- Put key terms in title and first paragraph.
- Use specific H2/H3 headings that match user query language.
- Keep repeated boilerplate minimal so snippets stay informative.
Review Heuristics
A documentation journey is healthy when:
- users can identify their path within 10 seconds on a section index page
- users can complete primary tasks without opening more than 2-3 tabs
- users can recover from common errors without external support tickets