Design and govern documentation taxonomy decisions including task-based vs topic-based categorization, hybrid models, split/nest rules, content model metadata schemas, controlled vocabulary for labels, and taxonomy governance boards. Use when organizing docs categories, deciding how to split or nest content, defining content models, or establishing labeling conventions. Triggered by: taxonomy, categorization, content model, split or nest, task-based, topic-based, labels, vocabulary, metadata schema, docs organization, content structure, IA, information architecture, classification, tagging.
Make and enforce decisions about how documentation content is categorized, labeled, and organized. Taxonomy is the invisible skeleton beneath navigation — when it's wrong, users can't find content even when navigation looks correct. This skill provides decision frameworks for categorization, split/nest rules, and controlled vocabulary governance.
This skill handles categorization logic. Physical navigation structure is handled by designing-navigation-systems. Individual page structure is handled by docs-designer.
Organize by what the user wants to accomplish.
├── get-started/
├── deploy/
├── authenticate/
├── monitor/
├── migrate/
└── troubleshoot/
| Strength | Weakness |
|---|---|
| Matches user intent directly | Doesn't scale when tasks cross domains |
| Easy for new users to navigate | Expert users may find it redundant |
| Maps cleanly to Diataxis How-to quadrant | Hard to place concept/explanation content |
Organize by product domain or feature area.
├── workspaces/
├── authentication/
├── billing/
├── api/
├── cli/
└── webhooks/
| Strength | Weakness |
|---|---|
| Scales well with product complexity | New users don't know which "topic" to visit |
| Maps to product architecture | Cross-cutting concerns lack a home |
| Experts can navigate directly | Assumes domain knowledge |
Use task-based at the top level, topic-based within sections.
├── get-started/ ← Task-based (top level)
│ ├── quickstart.mdx
│ └── first-deployment.mdx
├── guides/ ← Task-based (top level)
│ ├── authentication/ ← Topic-based (second level)
│ │ ├── setup-sso.mdx
│ │ └── manage-api-keys.mdx
│ ├── deployment/ ← Topic-based (second level)
│ │ ├── deploy-to-aws.mdx
│ │ └── configure-ci.mdx
│ └── billing/
│ └── manage-plans.mdx
├── reference/ ← Diataxis quadrant (top level)
│ ├── api/ ← Topic-based (second level)
│ └── cli/
└── explanation/ ← Diataxis quadrant (top level)
├── architecture.mdx
└── security-model.mdx
Hybrid rules:
When a section grows, you face a choice: split into siblings or nest as children.
Is the content about the SAME concept at DIFFERENT depths?
→ YES → NEST (parent-child)
→ NO → Are they PEER concepts at the SAME depth?
→ YES → SPLIT (siblings)
→ NO → RECLASSIFY (wrong section)
| Scenario | Decision | Example |
|---|---|---|
| "Authentication" has SSO, API Keys, OAuth | NEST under Authentication | auth/sso.mdx, auth/api-keys.mdx |
| "Authentication" and "Authorization" are peers | SPLIT as siblings | auth/, authorization/ |
| "Webhooks" appears under both API and Events | RECLASSIFY — pick one home | api/webhooks/ with cross-link from Events |
| A single page exceeds 2000 words | SPLIT into subpages | deploy/ → deploy/aws.mdx, deploy/gcp.mdx |
| A section has only 1-2 pages | MERGE upward into parent | Don't create monitoring/ for just one page |
| Metric | Threshold | Action |
|---|---|---|
| Pages in a group | > 12 | Split into subgroups |
| Word count per page | > 2000 | Split into subpages |
| Sections at one level | > 8 | Nest some as subgroups |
| Pages in a section | < 3 | Merge into parent section |
| Nesting depth | > 3 | Flatten — restructure taxonomy |
Every documentation page should have metadata that enables governance, search, and lifecycle management.
---