# 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