Documentation Structure
Good structure helps users find what they need quickly. Organize content by user tasks and mental models, not by internal system organization.
Content Hierarchy
Documentation/
├── Welcome/ # Entry point, product overview
├── Getting Started/ # First steps, quick wins
├── Guides/ # Task-oriented documentation
│ ├── Understanding X # Conceptual
│ ├── Use Cases # Real-world scenarios
│ └── Best Practices # Recommendations
├── API Reference/ # Technical reference
│ ├── Introduction # API overview
│ └── Endpoints/ # Per-resource documentation
└── Updates/ # Changelog, versioning
Page Structure Patterns
| Page Type | Structure |
|---|---|
| Overview | Brief description → "In this section you will find:" → Linked list of child pages |
| Conceptual | Lead paragraph → Key characteristics (bullets) → How it works → Subtopics with --- dividers → Related concepts |
| Task-Oriented | Brief context → Prerequisites → Numbered steps → Verification → Next steps |
Section Dividers
Use --- between major sections for visual separation.
When to use:
- Between major topic changes
- Before "Related" or "Next steps" sections
- After introductory content
- Before prerequisites in guides
Don't overuse: Not every heading needs a divider.
Navigation Patterns
| Pattern | Usage |
|---|---|
| Breadcrumb | Show hierarchy: Guides > Core Entities > Accounts |
| Prev/Next | Connect sequential content: [Previous: Assets] | [Next: Portfolios] |
| On-this-page | For long pages, show section links at top |
Information Density
Scannable content:
- Lead with key point in each section
- Use bullet points for 3+ items
- Use tables for comparing options
- Use headings every 2-3 paragraphs
- Bold key terms on first use
Progressive disclosure:
- Essential info (80% of users need) first
- Advanced configuration in separate section
- Edge cases and rare scenarios last
Tables vs Lists
Use tables when: Comparing items across same attributes, showing structured data (API fields), displaying options with consistent properties
Use lists when: Items don't have comparable attributes, sequence matters (steps), items have varying detail levels
Code Examples Placement
| Type | When |
|---|---|
| Inline code | Short references: "Set the assetCode field..." |
| Code blocks | Complete, runnable examples |
Rules:
- Show example immediately after explaining it
- Keep examples minimal but complete
- Use realistic data (not "foo", "bar")
- Show both request and response for API docs
Cross-Linking Strategy
- Link first mention of a concept in each section
- Don't over-link – once per section is enough
- Link destinations: Concept → conceptual docs, API action → endpoint, "Learn more" → deeper dive
Page Length Guidelines
| Page Type | Target | Reasoning |
|---|---|---|
| Overview | 1-2 screens | Quick orientation |
| Concept | 2-4 screens | Thorough explanation |
| How-to | 1-3 screens | Task completion |
| API endpoint | 2-3 screens | Complete reference |
| Best practices | 3-5 screens | Multiple recommendations |
If >5 screens, consider splitting.
Quality Checklist
- Content organized by user task, not system structure
- Overview pages link to all child content
- Section dividers separate major topics
- Headings create scannable structure
- Tables used for comparable items
- Code examples follow explanations
- Cross-links connect related content
- Page length appropriate for type
- Navigation connects sequential content
Standards Loading (MANDATORY)
Before planning documentation structure:
- Understand content types - What documents will exist (conceptual, how-to, API reference)
- Load writing skills -
ring:writing-functional-docsandring:writing-api-docs - Review existing structure - Understand current documentation hierarchy
HARD GATE: CANNOT reorganize documentation without understanding content and audience.
Blocker Criteria - STOP and Report
| Condition | Decision | Action |
|---|---|---|
| Content inventory incomplete | STOP | Report: "Need complete list of documentation topics" |
| User tasks undefined | STOP | Report: "Need user task list to organize around" |
| Information architecture undefined | STOP | Report: "Need IA decisions before structuring" |
| Navigation requirements unclear | STOP | Report: "Need navigation pattern decisions" |
Cannot Be Overridden
These requirements are NON-NEGOTIABLE:
- MUST organize by user tasks (not system structure)
- MUST include overview pages that link to children
- MUST use section dividers (
---) between major topics - MUST keep page length appropriate for document type
- CANNOT nest deeper than H3 without good reason
- CANNOT create orphan pages (must be linked)
Severity Calibration
| Severity | Criteria | Examples |
|---|---|---|
| CRITICAL | Completely disorganized, no navigation | No hierarchy, orphan pages everywhere |
| HIGH | Organized by system, not user tasks | "Database tables" instead of "Managing accounts" |
| MEDIUM | Missing links, poor scannability | No cross-links, walls of text |
| LOW | Structure works but could be optimized | Could improve navigation, add dividers |
Pressure Resistance
| User Says | Your Response |
|---|---|
| "Organize by our system components" | "MUST organize by user tasks. System structure ≠ mental model. I'll structure around what users do." |
| "One long page is fine" | "Long pages overwhelm users. MUST split by document type guidelines. I'll organize appropriately." |
| "Skip the overview pages" | "Overview pages are REQUIRED for navigation. I'll create overview pages linking to children." |
| "Cross-links are extra work" | "Cross-links enable discovery. MUST connect related content. I'll add appropriate links." |
| "Flat structure is simpler" | "Flat structure makes finding content harder. MUST use appropriate hierarchy." |
Anti-Rationalization Table
| Rationalization | Why It's WRONG | Required Action |
|---|---|---|
| "Mirrors our codebase structure" | Users don't know your codebase | MUST organize by user tasks |
| "Everything on one page is convenient" | Convenience for whom? Not users | Split per page length guidelines |
| "Deep nesting shows thoroughness" | Deep nesting hides content | Keep hierarchy shallow (H3 max) |
| "Users will search anyway" | Search supplements, not replaces structure | MUST provide clear navigation |
| "Links can be added later" | Orphan pages are lost pages | Add links during creation |
| "Structure is aesthetic, not functional" | Structure IS functionality | Structure enables findability |
When This Skill is Not Needed
Signs that documentation structure is already correct:
- Content organized around user tasks and goals
- Clear hierarchy with appropriate depth
- Overview pages link to all child content
- Section dividers separate major topics
- Navigation connects sequential content
- Cross-links connect related topics
- Page lengths appropriate for document type
- No orphan pages
If all above are true: Structure is correct, no reorganization needed.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.