Lerianstudio Ring Documentation Structure

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

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

Information Density

Scannable content:

1. Lead with key point in each section
2. Use bullet points for 3+ items
3. Use tables for comparing options
4. Use headings every 2-3 paragraphs
5. 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

Rules:

1. Show example immediately after explaining it
2. Keep examples minimal but complete
3. Use realistic data (not "foo", "bar")
4. 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

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:

1. Understand content types - What documents will exist (conceptual, how-to, API reference)
2. Load writing skills - ring:writing-functional-docs and ring:writing-api-docs
3. Review existing structure - Understand current documentation hierarchy

HARD GATE: CANNOT reorganize documentation without understanding content and audience.

Blocker Criteria - STOP and Report

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

Pressure Resistance

Anti-Rationalization Table

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.