Categories and sub-categories
How to organize your help center using one level of nesting. Naming, ordering, and when to split.
Categories and sub-categories
A help center is only as useful as its structure. Ochre keeps the structure deliberately shallow: one level of nesting. A parent category can contain articles, sub-categories, or both. A sub-category can only contain articles.
That is it. No grand-children, no infinite trees.
Why one level
Three reasons.
First, customers do not read past two clicks. If they have to drill down three levels to find an article, they email support instead. Shallow trees outperform deep ones in every analytics report we have seen.
Second, AI retrieval works better against a flat structure. Categories are mostly a navigation aid for humans. The AI matches against article content directly. See The brain: KB graph.
Third, deep trees rot. Maintaining four-level docs is more work than most teams have. We chose the constraint.
Creating a category
From the Knowledge section, click Categories then New category. Give it a name, a slug, and an optional icon. The slug is the URL path: /help/<workspace-slug>/category/<slug>.
Categories show up in the help center navigation in the order you set. Drag to reorder, or set a numeric position in the sidebar.
Creating a sub-category
Open a parent category and click Add sub-category. Same fields. Sub-categories render as sections inside the parent's page.
You can move a sub-category to a different parent later, but the URL changes. Inbound links break unless you set redirects. Pick the structure once if you can.
Naming
Match what your customers say, not what your team says.
- "Billing" beats "Subscription Management".
- "Email" beats "Inbound Email Channels".
- "Getting started" beats "Onboarding Procedures".
If you are unsure, look at the search queries in Article analytics. Use the words customers type.
A starter structure
For most B2B SaaS, this works on day one:
- Getting started
- Inbox
- AI agent
- Knowledge base
- Customers
- Channels
- Integrations
- Billing
- Troubleshooting
Add sub-categories only when a category passes ~15 articles. Below that, sub-categories add navigation overhead without clarity benefit.
Article placement
Each article belongs to exactly one category or sub-category. Pick the one a customer would search first. If two categories feel right, put it in the more specific one and link from the other using a one-line stub article.
For cross-cutting topics, pick a primary home and use internal links to surface from related articles.
Position and sort order
Within a category, articles render in position order. Lower numbers come first. Ties break alphabetically.
Use round numbers (10, 20, 30) so you can insert later without renumbering everything. The "important first" articles deserve manual positions. The long tail can stay alphabetical.
Hiding categories
Categories do not have a visibility toggle of their own. To hide a category, archive every article inside it or set them all to draft. Empty categories do not render. See Article visibility and gating.
Renaming and re-slugging
Renaming a category changes the display name immediately. Re-slugging changes the URL. Outbound links to the old slug 404 unless you set up redirects.
Best practice: lock slugs early. Names can change, slugs should not.
Sub-category nesting limit
Sub-categories cannot contain other sub-categories. If you find yourself wanting that, you have outgrown the structure or you are over-organizing. Usually it is the latter.
The fix is almost always to flatten and let titles do the work. "Setting up Stripe webhooks" is a clear title. Burying it three levels deep does not make it clearer.
Cross-category linking
Articles in different categories link freely. Use [Title](/help/ochre/slug) regardless of where the target lives. The category is purely structural; links do not care.
This is how you handle the "where do I put it" problem. Put it once, link from everywhere it is relevant. See for example how AI overview cross-links into the knowledge base section through articles like The brain: KB graph.
SEO interaction
Categories get their own SEO metadata. Set the category title and description to something a search engine can use as a landing page. Think "Billing help and FAQs" not "Billing".
Article SEO is independent. See Article SEO.
When to reorganize
If your help center has been running for six months, look at:
- Categories with zero articles in the top 20 most viewed.
- Categories with only one article (merge it).
- Articles in the top 20 buried under sub-categories (promote them).
A small reorg every six months is healthier than a big one every two years. Use Article analytics as the input, not vibes.
Related
Was this article helpful?