---
title: How to structure documentation navigation
description: Design navigation around what readers are trying to do, keep it shallow, and validate it against real use.
---
Navigation is the first model of your product a reader sees. Before they read a word of
any page, the sidebar has already told them what the pieces are and how they relate. Get
it right and readers find answers without thinking about where to look. Get it wrong and
they leave for a search engine, a support ticket, or someone else's docs.
This guide covers how to design that structure, how to check it against real behavior,
and how to keep it coherent as the docs grow. On Reed, the structure lives in one place —
the `navigation` field of `docs.json` — so every decision here ends up as an edit to that
file.
## Start with the product and the people using it
Do not open `docs.json` first. Talk to the people who know the product and its users.
### Map the foundation
Sit down with founders, product managers and engineering leads before you commit to a
structure. You want to learn how the product actually works, which is often not how the
marketing site describes it.
Useful questions:
- What is the shortest honest explanation of how the product works?
- What are its core building blocks?
- How do people usually adopt it, and where do they get stuck?
- Which integrations or dependencies matter most?
- If you split the product into layers, what are they? Do users think in tasks or in
features?
The answers expose the product's natural shape. They also expose the places where your
current docs have drifted away from it.
### Know who you are writing for
A developer wiring up an API, an admin changing settings and a new user following
onboarding each look for different things in different places. Decide who the navigation
is for before you arrange it.
If you have several distinct audiences, decide whether one structure can serve them or
whether they need separate paths. [Understand your audience](/docs/guides/understand-your-audience)
covers how to define them.
## Choose a structure
### Organize by journey, not by feature
The most common mistake is mirroring the org chart: one section per product team, one page
per feature. That is how the builders think. Readers arrive with a goal.
Compare two ways to lay out an API product:
| Feature-centric (avoid) | Journey-centric (prefer) |
|---|---|
| Core API | Get started |
| Authentication | Authenticate |
| Webhooks | Send your first request |
| Rate limiting | Handle errors |
| SDKs | Go to production |
The journey version tells a reader where they are in a process. The feature version only
helps someone who already knows the name of what they need.
### Map it onto tabs and groups
Reed gives you exactly two structural levels above the page, and then optional nesting:
- **Tabs** split the site into top-level areas, such as Docs, API and Changelog.
- **Groups** divide a tab into labelled sections in the sidebar.
- **Nested groups** go inside a group's `pages` list, up to five levels deep.
```json
{
"navigation": {
"tabs": [
{
"label": "Docs",
"groups": [
{ "label": "Get started", "pages": ["index", "quickstart"] },
{ "label": "Authenticate", "pages": ["auth/api-keys", "auth/oauth"] },
{
"label": "Go to production",
"pages": [
"production/checklist",
{ "label": "Monitoring", "pages": ["production/logs", "production/alerts"] }
]
}
]
}
]
}
}
```
That is the whole vocabulary. A tab can carry an `icon`; groups and pages cannot, and there
are no badges, anchors, dropdowns, version switchers or language pickers in navigation.
If a structure you are sketching
needs one of those, redraw it with tabs and groups — or, for versions and languages, see
the [roadmap](/docs/roadmap).
Each string in `pages` is a page id, derived from the file path: segments are slugified, a
nested `index` collapses to its directory, and a frontmatter `slug` overrides everything.
[Navigation](/docs/authoring/navigation) has all four rules. A page id that resolves to no
file is an error at `reed check`, so a sidebar entry can never point at nothing.
### Balance depth and breadth
Depth is how many levels a reader clicks through to reach a page. Breadth is how many
items sit at each level.
- **Keep each level to about seven items.** Past that, readers spend their attention
comparing options instead of choosing one.
- **Prefer a little depth to a lot of breadth.** Five groups with a handful of pages each
scan faster than twenty loose pages.
- **Keep critical pages within two levels.** Reed allows five levels of nesting. That is a
ceiling, not a target. If readers need a page often, it should not sit three groups down.
### Name things the way readers do
Labels should match how readers describe their goal, not what the feature is called
internally.
- Use verbs for task sections: "Authenticate", "Deploy", "Monitor".
- Use nouns for reference: "API reference", "CLI", "Changelog".
- Drop internal codenames and team jargon.
- Keep labels short. Under four words is a good rule; Reed caps tab and group labels at 100
characters, which is far more than you should use.
## Validate your assumptions
Your first structure is a guess. Treat it as one until real readers confirm it.
### Watch real journeys
The built site is static HTML with an in-browser search index, so there is no
server-side log of what people searched for or clicked. For traffic data, configure one of
the six analytics providers Reed supports — see [Analytics](/docs/site/analytics). Reed
does not let configuration inject arbitrary scripts, so a session-replay tool cannot be
added. With page-view data, look for:
- **Entry points.** Where do readers land — from search, from a support reply, from inside
your product?
- **Paths.** Do they follow the structure you designed, or cut across it?
- **Friction.** Where do they stop, double back, or leave?
- **Vocabulary.** Are they looking for words that never appear in your labels? That is a
terminology mismatch, and the fix is a rename, not a restructure.
### Test with people
Numbers show you where readers struggle. Conversations tell you why.
Give someone a specific task and ask them to complete it using only the docs, thinking out
loud. Where they click first, and where they hesitate, tells you whether the structure
makes sense to someone outside your team.
New hires are excellent test subjects. Before they learn the product from the inside, ask
them to find specific answers in the docs. Every place they get lost is an assumption your
navigation makes that insiders no longer notice.
## Find and fix common problems
### Too many top-level items
If a tab carries more than seven or eight groups, readers stall. Merge related groups
under a clearer name, or move a whole area into its own tab.
### Essential pages buried
If your most-used pages sit two or three levels deep, promote them. High-traffic pages
belong at the top of a tab or in the first level of the group that owns them.
### Labels that make people hesitate
If readers pause before clicking, the label is not doing its job. Test it: describe what
is inside and ask whether they would have predicted it from the label alone.
### A content gap disguised as a navigation problem
Sometimes readers cannot find a page because the page does not exist. If they are looking
for something no page covers, you are missing content, not mislabelling it. Tell the two
apart before you move anything.
## Iterate
Navigation should change as the product changes. It does not have to be right the first
time.
- **Revisit it whenever a major feature ships.** New features expose structural gaps.
- **Check reader vocabulary every quarter**, from whatever search or support data you
have, against your labels.
- **Rethink the top level once a year.** What worked at twenty pages rarely works at two
hundred.
Two Reed rules make structure easier to keep honest over time:
- **Every page must be listed in `navigation`.** There is no hidden-page feature: a file
left out fails `reed check` with `content-page-not-in-navigation`, so every new page
forces a placement decision before it can ship.
- **Empty tabs and groups are schema errors.** You cannot reserve a section for content
that does not exist yet. A tab appears when it has something to hold.
Run `reed check` on every pull request. It is offline and fast, and it fails on a page id
that does not resolve — the most common way a restructure breaks. See
[reed check](/docs/reference/cli/check).
Moving a file changes its page id, which changes its URL. When you restructure, add a
[redirect](/docs/site/redirects) for every page whose URL moved, and see
[How to link documentation pages effectively](/docs/guides/linking) for keeping internal
links in step.
## Frequently asked questions
By user goals, almost always. A feature layout suits people who already understand the
architecture, but readers come to docs to get something done. Organize around what they
are trying to do, and file each feature under the task it enables.
Aim for five to seven groups per tab, and only as many tabs as you have genuinely
separate areas. Past about seven options, readers slow down. If you have more, look for
natural pairs you can fold into one group with nested groups inside.
First decide whether they really need different structures. An admin and a developer
can often share a Get started group with audience-specific pages inside it. If their
journeys are fundamentally different, give each audience its own tab. If they are
effectively different products, consider separate Reed builds mounted at separate base
paths, since Reed has no product switcher.
When evidence shows readers consistently failing to find things: frequent support
questions about content that exists, searches for pages that should be one click away,
or test users getting lost in the same place. Do not restructure on instinct alone.
Moving pages changes their URLs, breaks bookmarks, and forces you to update internal
links and add redirects. Make sure the data justifies that cost.
Decide where a page goes before anyone writes it. Reed already enforces half of this: a
page that is not in navigation breaks the build, so every new page arrives with a
navigation change in the same pull request. Make reviewing that change part of reviewing
the page. Placement decided up front is far cheaper than reorganizing dozens of
misfiled pages later.