Skip to main content
Documentation often mirrors the product: features become sections, and the internal architecture becomes the docs hierarchy. That feels logical because it matches the team’s mental model. It rarely works well for users. Users don’t navigate docs by feature. They navigate by goal. They arrive asking “how do I do X?” If your navigation requires them to first understand your product’s architecture to know where to look, you’ve already made their job harder.

​
Feature-based vs. goal-based navigation

Here’s a concrete example. A company that builds a data pipeline tool might organize their docs like this:
This mirrors the product’s architecture. But a user who wants to “get data from Postgres into our data warehouse” has to infer which sections are relevant before they can even start reading. A goal-based alternative:
The underlying content is often identical. The organization reflects what users are trying to accomplish, not how the product is built.

​
The AI navigation trap

AI tools are particularly prone to generating feature-based navigation. Ask an AI to “suggest a navigation structure for our documentation” and it will almost certainly produce something that mirrors your product — because the most obvious input you give it is a list of features, and it’ll organize around that. If you’re using AI to help structure your Mintlify docs, be explicit about organizing by user goal:
“Suggest a navigation structure for our documentation organized around what users are trying to accomplish, not our product’s feature list. Our users are typically trying to: [list 3–5 key jobs to be done].”
That extra context usually produces a more useful structure.

​
Mintlify’s navigation primitives

Mintlify gives you several ways to organize navigation. Choosing the right one matters — each is suited to a different structural need.

​
Groups

Groups are the basic building block: a labeled section with pages inside. Use them when the pages inside share a clear purpose and a user who wants one is likely to want the others.
docs.json
Keep group names short and goal-oriented. “Get started” works. “Introduction to the product” is too long and too vague. “Core concepts” is product-oriented and rarely tells users whether they need to read it.

​
Tabs

Tabs create distinct sections of your site with separate URL spaces. Use them to separate content for meaningfully different audiences or use cases. Completing a single task should only require content from a single tab. The most common good use of tabs: separating conceptual guides from a technical API reference. Users reading guides are in a different mode than users looking up endpoint parameters. Mixing them creates noise for both. A common misuse of tabs: creating a tab for every product area because the sidebar is getting long. A long sidebar is usually a signal that you have too much content or poorly defined groups, not that you need more tabs.

​
Products

Products are for organizations with genuinely separate products or product lines that serve different audiences. If a user who works with Product A rarely needs Product B’s documentation, products make sense. If users regularly move between sections, you’re better served with tabs or groups.

​
Anchors

Anchors create persistent navigation items at the top of your sidebar. Use them for resources that are genuinely useful from anywhere in your docs — a changelog, a status page, a community forum. Don’t use anchors to promote content that’s already accessible through your main navigation.

​
Patterns that hold up

Quickstart first, always. The most important page on most documentation sites is the one that gets a new user to a working state as fast as possible. It should be the first page in your primary navigation group — not buried under an “Overview” or “Introduction” that new users have to read first. Separate doing from looking up. Tutorials and how-to guides are about doing. Reference material is about looking up. Users move between these modes constantly, and they’re easier to navigate when they live in distinct areas of your Mintlify site. Name sections for what users will accomplish, not what the section contains. “Webhooks” describes what’s inside. “Receive real-time events” describes why a user would go there. The second version attracts the right reader without requiring them to already know what webhooks are.

​
Test your navigation before you commit

For a quick check, look at each section name without reading the content. Can a new user tell from the name alone whether the section will help with their task? If the answer is often no, the problem is usually one of two things: section names that are too product-centric, or sections that are too broad and need to be broken up. A more rigorous test: share just the navigation structure — section names only, no content — with a colleague who hasn’t worked closely on the docs. Ask them to point to where they’d go to accomplish three or four specific tasks. Where they click first tells you more than any analytics report.

​
Inventory content before reorganizing it

Before changing a large navigation tree, list the existing pages with their purpose, audience, content type, traffic, and owner. Mark duplicates, gaps, and pages that no longer deserve a place in the new structure. Designing from an inventory prevents two common mistakes: preserving every old page because it already exists, and moving pages without noticing that several cover the same task. When you rename or move a published page, add a redirect from the old URL to the new one. Existing bookmarks, search results, support messages, and agent citations may continue using the old address long after the navigation changes. Next up: Measure and improve findability — Use behavior and feedback to test whether the structure works.