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)

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.

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