/structuring-documentation

name: ring:structuring-documentation
description: "Structuring documentation: content hierarchy, overview/conceptual/task page structures, section dividers, navigation, tables-vs-lists, code placement, cross-linking, and page-length targets. Use when planning doc structure, organizing a content hierarchy, splitting content across pages, or designing navigation. Skip when writing the actual content, or checking voice (use ring:applying-voice-and-tone)."

Documentation Structure

When to use

• Planning documentation structure
• Organizing content hierarchy
• Deciding how to split content across pages
• Creating navigation patterns

Skip when

• Writing content → dispatch the guide-writer or api-writer agent
• Checking voice → use ring:applying-voice-and-tone

Related

**Complementary:** ring:applying-voice-and-tone, ring:reviewing-docs

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:** 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

| Type | When | |------|------| | Inline code | Short references: "Set the `assetCode` field..." | | Code blocks | Complete, runnable examples |

**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

| 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

---