John Lancaster
75 lines
2.3 KiB
Markdown
75 lines
2.3 KiB
Markdown
# 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:
|
|
|
|
1. Learn (concepts, architecture, mental models)
|
|
2. Do (task/how-to paths)
|
|
3. Reference (API, config, command catalog)
|
|
4. Troubleshoot (symptoms, diagnostics, fixes)
|
|
|
|
!!! info "IA references"
|
|
- [Diataxis framework](https://diataxis.fr/)
|
|
- [Divio documentation system](https://documentation.divio.com/)
|
|
|
|
## 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
|
|
|
|
1. Keep navigation labels user-facing and action-oriented.
|
|
2. Avoid duplicate labels in separate branches.
|
|
3. Place high-frequency tasks near the top.
|
|
4. Keep section depth shallow where possible.
|
|
|
|
!!! info "Relevant Zensical configuration docs"
|
|
- [Navigation setup](https://zensical.org/docs/setup/navigation/)
|
|
- [Search setup](https://zensical.org/docs/setup/search/)
|
|
- [Header setup](https://zensical.org/docs/setup/header/)
|
|
- [Footer setup](https://zensical.org/docs/setup/footer/)
|
|
|
|
## 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
|