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-docs and ring: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.