This framework defines how to structure documentation for a software product from scratch. It covers navigation hierarchy, content grouping principles, and the decisions you make before writing a single page.
Most documentation failures are not writing failures — they are findability failures. A user arrives with a clear question, can’t locate the answer in the navigation or through search, and gives up. They either submit a support ticket (costing the company money) or assume the product can’t do what they need.
Good information architecture means users reach the right content within two or three clicks from the documentation home page.
Developer documentation typically needs four navigation areas, aligned to the user’s intent:
| Area | What the user’s question is | Examples |
|---|---|---|
| Learning | “What is this and how does it work?” | Overview, key concepts, architecture |
| Doing | “How do I accomplish a specific task?” | How-to guides, tutorials, quickstarts |
| Reference | “What are the exact parameters, options, and return values?” | API reference, CLI reference, config options |
| Troubleshooting | “Something isn’t working — why?” | Error code lookup, common issues, FAQ |
This model — popularized by the Diátaxis framework — prevents a common failure mode where docs mix conceptual explanation with step-by-step instructions, making it hard to skim for either purpose.
Map your content against this model before writing anything:
| Your content | Probably belongs in |
|---|---|
| “The workflow engine uses an event-driven model…” | Learning (concept) |
| “Configure a retry policy for your workflow” | Doing (how-to) |
“NexaFlow({ apiKey, timeoutMs })” |
Reference |
| “My webhook isn’t receiving events” | Troubleshooting |
For a developer-facing documentation site, this is the recommended top-level structure. Not all products need every section.
Docs home
├── Getting started ← Doing (quickstart)
├── Concepts ← Learning
│ ├── Overview
│ ├── Architecture
│ └── [Core concept pages]
├── Guides ← Doing (task-based how-tos)
│ ├── [Task-based guide pages]
│ └── ...
├── API reference ← Reference
│ ├── [Resource/class pages]
│ └── ...
├── Troubleshooting ← Troubleshooting
│ ├── Common errors
│ └── ...
├── What's new ← Changelog / release notes
└── Support / Contact
Hierarchy rules:
Navigation labels must be short and outcome-oriented. Users scan navigation to find the thing that answers their question — not to understand the product’s architecture.
| Avoid | Use |
|---|---|
| “NexaFlow SDK Documentation” | “Docs” or just the product name |
| “Workflow Engine Architecture” (top-level) | Move this inside Concepts |
| “Frequently Asked Questions” | “Troubleshooting” or “Common issues” |
| “Release Notes and Changelog” | “What’s new” or “Changelog” |
| “Advanced Configuration Options” | “Configuration reference” |
Group by user task, not by feature. A user looking to handle payment failures doesn’t think “I need the webhook section and the error codes section” — they think “I need to handle payment failures.” Create a guide around the task and link from it to the reference pages.
Co-locate decisions. Information that a user needs at the same moment should be on the same page or one click away. If a user is following a setup guide and gets blocked by an authentication error, the troubleshooting path should be accessible from the setup guide — not buried three levels down.
Separate concepts from tasks. A conceptual explanation of how retry logic works belongs in a Concepts page. A step-by-step guide to adding retry logic belongs in a Guides page. They can and should link to each other, but they serve different user intents and should not be on the same page.
Documentation accumulates debt the same way code does. Pages become stale. Navigation grows into a graveyard of old feature names. Links rot.
Manage doc debt by:
External search engines rank documentation differently than they rank marketing pages. Optimize for developers who search with specific technical terms.