A documentation site should carry between four and seven top-level sections, nest no deeper than two levels, and name every section after the reader’s task rather than your product’s internals. Structure is the thing readers hit first and writers think about last, and it is the largest single cause of documentation nobody can use.
This guide covers how to decide on sections, how deep to nest, what page types you actually need, and a five-step process for pulling an existing site back into shape.
Why structure matters more than writing quality
A page nobody can find is worth exactly nothing, however well it is written. Readers do not read documentation. They arrive mid-task, from a search engine or a support reply, scan for the shape of an answer, and leave. Every extra decision you put between them and that answer costs you a percentage of them.
This is why restructuring usually beats rewriting. Teams reach for a style guide when their support queue fills up with questions the docs already answer, but the pages are almost always there. Readers simply could not find them, or found them and could not tell they were the right ones.
Open your analytics, list the ten most-visited pages, and count the clicks from the home page to each one. Anything over three is a structural problem, and no amount of editing will fix it.
How many top-level sections should a documentation site have?
Four to seven. The sidebar is scanned, not read: past about seven items a reader stops scanning and reaches for search instead, which means your navigation has stopped doing its job. Fewer than four usually means at least one section is a dumping ground.
A set that works for most software products:
- Getting started: installation and a first successful outcome, nothing else
- Guides: task-shaped walkthroughs for things people actually do
- Reference: exhaustive, boring, alphabetised where possible
- Integrations: one page per third-party system, if you have more than three
- Troubleshooting: symptoms as headings, in the reader’s words
- Release notes: dated, newest first, with breaking changes called out
If a proposed section would hold fewer than three pages, it is not a section. Fold it into a neighbour and give it a heading instead.
How deep should documentation navigation nest?
Two levels. Section, then page. A third navigation level is almost always a page that should have been a heading inside its parent, and the cost of getting this wrong compounds: URLs grow unwieldy, breadcrumbs wrap, and on a phone the reader has to open two drawers before seeing a single link.
Depth inside a page is free, though, and that is where the third level belongs. A long reference page with a good table of contents is easier to use than three short pages nested under one another, because it is searchable in one keystroke with the browser’s own find.
If a reader has to open three folders to reach a page, the page may as well not exist.
The four page types every documentation site needs
Most structural confusion comes from mixing page types: a tutorial that keeps stopping to explain architecture, or a reference page with a narrative introduction. The Diátaxis framework, developed by Daniele Procida, separates them cleanly, and it is worth adopting even if you never mention it to your readers.
| Page type | Answers | Reader’s state | Example |
|---|---|---|---|
| Tutorial | Teach me the basics | New, no context, needs a win | Build your first integration |
| How-to guide | How do I do X? | Working, has a specific goal | Rotate an API key |
| Reference | What are the exact parameters? | Mid-task, needs one fact | Webhook event payloads |
| Explanation | Why does it work this way? | Evaluating or debugging | How rate limiting works |
The practical test: if you cannot say which of the four a page is, your readers cannot either. Split it.
How should you name sections and pages?
Naming is where most documentation quietly fails, because the names make perfect sense to the team that chose them.
- Use the reader’s vocabulary, not your codebase’s. If your users say “login” and your services say “identity”, the page is called Login.
- Lead task pages with a verb. “Configure SSO”, not “SSO configuration”, because it matches how people search.
- Lead reference pages with the noun. That is how people scan an index.
- Front-load the distinguishing word. Six pages beginning “Advanced” are six pages that look identical in a sidebar.
- Never be clever. A section called “The Workshop” costs a reader a click to find out what it is.
- Keep titles under about sixty characters so they survive a search result, a browser tab and a mobile sidebar intact.
A five-step process for restructuring an existing site
This works on a site of a few hundred pages and takes a couple of days, most of it in step one.
-
Inventory everything. One row per page: URL, title, owner, last meaningful update, monthly views. Do not skip this and work from memory: the inventory is where you discover the forty pages nobody has opened since 2023.
-
Delete and merge before you organise. Anything stale, duplicated or unvisited goes now. Restructuring content you are about to delete is wasted work, and a smaller site is a better site.
-
Assign each surviving page exactly one type: tutorial, how-to, reference or explanation. Pages that resist are pages that need splitting.
-
Group into four to seven sections by reader task, not by internal team ownership. Whose team maintains a feature is invisible to the person reading about it.
-
Fix the URLs and redirect the old ones. Every inbound link, bookmark and support macro points at the old structure. A restructure without redirects is an outage.
Documentation URLs live in support tickets, Slack threads, blog posts and other people’s code comments for years. Map every old path to its new home before launch, and keep the map.
How do you know the structure is working?
Four signals, in rough order of usefulness:
- The search-to-navigation ratio falls. Heavy search use means the sidebar is not answering the question “where would that live?”
- Support answers become links. When your team can resolve a ticket by pasting a URL, the page was findable.
- Landing pages spread out. If every session starts at the home page, people are navigating from the top because they cannot enter in the middle.
- Nobody asks where to put a new page. A structure that is obvious to writers is usually obvious to readers.
Where to start
Do the inventory. It is unglamorous, and the only step that reliably changes anyone’s mind, including your own, about what the site actually contains. Everything after it is comparatively easy.
If you are building on WordPress, Doku models this structure directly: documentation lives in its own post type with hierarchical categories driving a two-level sidebar. See Structure for how sections, ordering and parent pages fit together.