Structure is the part of documentation that is cheap to get right at the start and expensive to fix later, because fixing it means moving URLs. It is worth an afternoon of thought before you write the first article.
Start with the four types
The most useful idea in documentation architecture is that there are four distinct kinds of content, they serve different reader states, and mixing them produces an article that serves nobody well. The framework is usually credited to Diataxis, and it is worth understanding even if you never adopt the vocabulary.
A tutorial teaches by doing: the reader is learning, follows steps, and reaches a result. A how-to guide serves a reader with a specific goal who already knows roughly what they are doing. Reference is for looking something up - parameters, limits, error codes - and is read in fragments, never start to finish. Explanation gives context and rationale, and is read when someone wants to understand rather than to act.
- Tutorial: 'Build your first integration' - learning-oriented, a guaranteed outcome, no choices.
- How-to: 'Rotate an API key' - goal-oriented, assumes competence, gets to the point.
- Reference: 'API error codes' - information-oriented, complete, consistently structured.
- Explanation: 'How our rate limiting works' - understanding-oriented, discusses trade-offs.
Organise categories around tasks
The two most common structures both fail for the same reason: they reflect how you think rather than how the reader thinks. Organising by internal team means a reader has to know which department owns their answer. Organising by product menu means they have to already know where the feature lives - which is often exactly what they are trying to find out.
Task-based categories work because readers arrive with a goal. 'Setting up billing', 'Managing users', 'Troubleshooting imports' are guessable from a reader's intent without any knowledge of your internals.
Test the structure cheaply before you commit to it. Take ten common questions from your support queue, give the category list to five people outside the team, and ask which category each question belongs in. Disagreement between testers is your signal.
- Five to nine top-level categories. Fewer become dumping grounds; more stop being scanned.
- Two levels of hierarchy is almost always enough. Three suggests the top level is wrong.
- Every category should be guessable from a reader's goal, without insider knowledge.
- 'Getting started', 'FAQ' and 'Other' are warning signs - they collect what the structure failed to place.
Name things the way readers say them
Vocabulary is where most structures quietly fail. Your team says 'tenant'; your customers say 'account'. Your team says 'ingestion'; your customers say 'import'. Every one of these mismatches is a search that returns nothing.
Take names from your failed-search report, from support ticket subject lines, and from sales call recordings. Then mention your internal term inside the article so both vocabularies find it. Keep a terminology list and enforce it - one term for one thing, everywhere.
Design the landing page around the top ten questions
Most teams design the home page around product areas. Readers do not arrive wanting a product area; they arrive wanting an answer to one of a fairly short list of questions.
Put search first and make it prominent - for most knowledge bases it carries more traffic than every navigation link combined. Below it, list the ten most-viewed articles by name rather than showing category tiles. Category tiles look tidier and perform worse, because a named article tells a reader whether their answer is behind it.
Plan for growth from the start
A structure that works at twenty articles often collapses at two hundred, because the categories were defined by what existed rather than by what the domain contains.
Define categories around your product's conceptual areas, not around the articles you happen to have written. An empty category is a to-do item, which is more useful than a category that has to be split later. Splitting is what forces URL changes, and URL changes are what cost you rankings.
- Define categories from the domain, not from the current article list.
- It is fine for a category to start with two articles in it.
- Avoid category names that describe volume ('Advanced', 'More') - they never stop growing.
- Keep URLs stable; when you must move one, always redirect.
Know when to restructure - and when not to
Restructuring feels productive and is frequently the wrong instinct. The signal that structure is genuinely the problem is specific: readers searching for content that exists and not finding it. That shows up as failed searches whose answers are already written.
If instead the failed searches are for content you do not have, that is a content problem and restructuring will not help. If readers find articles but rate them unhelpful, that is a writing problem. Diagnose before you reorganise.
When you do restructure, do it in one deliberate pass with a complete redirect map, rather than opportunistically over six months. Partial restructures leave readers and search engines with two half-true mental models of your documentation.