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.

ring:documentation-structure