Skip to main content
Most documentation navigation is organized around the product. Features become sections. The product’s internal architecture becomes the docs hierarchy. This feels logical because it’s how the team thinks about the product. 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?” — and 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: 
Sources
Destinations
Transformations
Connectors
Settings
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: 
Get started
Connect your data
Transform and model
Reference
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].”
You’ll get substantially more useful output.

​
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
{
  "group": "Get started",
  "pages": ["quickstart", "authentication", "first-api-call"]
}
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 — not to break up a lot of content that happens to serve the same reader. 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

The fastest check: look at each section name in isolation, without reading any of the content. Can a new user tell from the name alone whether that section is relevant to what they’re trying to do? 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. Next up: Keep docs accurate as your product grows — a maintenance process that uses automation and AI to prevent your documentation from going stale.