gh-lerianstudio-ring-tw-team/skills/documentation-structure/SKILL.md

---
name: documentation-structure
description: |
  Patterns for organizing and structuring documentation including hierarchy,
  navigation, and information architecture.

trigger: |
  - Planning documentation structure
  - Organizing content hierarchy
  - Deciding how to split content across pages
  - Creating navigation patterns

skip_when: |
  - Writing content → use writing-functional-docs or writing-api-docs
  - Checking voice → use voice-and-tone

related:
  complementary: [writing-functional-docs, writing-api-docs]
---

# 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

### Top-Level Organization

Structure documentation around user needs:

```
Documentation/
├── Welcome/              # Entry point, product overview
├── Getting Started/      # First steps, quick wins
├── Guides/              # Task-oriented documentation
│   ├── Understanding X   # Conceptual documentation
│   ├── Installing X     # Setup and deployment
│   ├── Use Cases        # Real-world scenarios
│   ├── Core Entities    # Domain concepts
│   └── Best Practices   # Recommendations
├── API Reference/       # Technical reference
│   ├── Introduction     # API overview
│   ├── Getting Started  # Quick start
│   └── Endpoints/       # Per-resource documentation
└── Updates/             # Changelog, versioning
```

---

## Page Structure Patterns

### Overview Pages
Introduce a section and link to child pages.

```markdown
# Section Name

Brief description of what this section covers and who it's for.

---

## Content

In this section, you will find:

- [**Topic A**](link): Brief description
- [**Topic B**](link): Brief description
- [**Topic C**](link): Brief description
```

---

### Conceptual Pages
Explain a single concept thoroughly.

```markdown
# Concept Name

Lead paragraph defining the concept and its importance.

## Key characteristics

- Point 1
- Point 2
- Point 3

## How it works

Detailed explanation with diagrams.

---

## Subtopic A

Content about subtopic A.

---

## Subtopic B

Content about subtopic B.

---

## Related concepts

- [Related A](link) – Connection explanation
- [Related B](link) – Connection explanation
```

---

### Task-Oriented Pages
Guide users through a specific workflow.

```markdown
# How to [accomplish task]

Brief context on when and why.

## Prerequisites

- Requirement 1
- Requirement 2

---

## Step 1: Action name

Explanation of what to do.

## Step 2: Action name

Continue the workflow.

---

## Verification

How to confirm success.

## Next steps

- [Follow-up task](link)
- [Related task](link)
```

---

## Section Dividers

Use horizontal rules (`---`) to create visual separation between major sections.

```markdown
## Section One

Content here.

---

## Section Two

New topic content here.
```

**When to use dividers:**
- 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. Use them for significant transitions.

---

## Navigation Patterns

### Breadcrumb Context
Always show where users are in the hierarchy:

```
Guides > Core Entities > Accounts
```

### Previous/Next Links
Connect sequential content:

```markdown
[Previous: Assets](link) | [Next: Portfolios](link)
```

### On-This-Page Navigation
For long pages, show section links:

```markdown
On this page:
- [Key characteristics](#key-characteristics)
- [How it works](#how-it-works)
- [Managing via API](#managing-via-api)
```

---

## Information Density

### Scannable Content
Users scan before they read. Make content scannable:

1. **Lead with the key point** in each section
2. **Use bullet points** for lists of 3+ items
3. **Use tables** for comparing options
4. **Use headings** every 2-3 paragraphs
5. **Use bold** for key terms on first use

---

### Progressive Disclosure

Start with essentials, then add depth:

```markdown
# Feature Overview

Essential information that 80% of users need.

---

## Advanced Configuration

Deeper details for users who need them.

### Rare Scenarios

Edge cases and special situations.
```

---

## Tables vs Lists

### Use Tables When:
- Comparing multiple items across same attributes
- Showing structured data (API fields, parameters)
- Displaying options with consistent properties

```markdown
| Model | Best For | Support Level |
|-------|----------|---------------|
| Community | Experimentation | Community |
| Enterprise | Production | Dedicated |
```

### Use Lists When:
- Items don't have comparable attributes
- Sequence matters (steps)
- Items have varying levels of detail

```markdown
## Key features

- **Central Ledger**: Real-time account and transaction management
- **Modularity**: Flexible architecture for customization
- **Scalability**: Handles large transaction volumes
```

---

## Code Examples Placement

### Inline Code
For short references within text:

> Set the `assetCode` field to your currency code.

### Code Blocks
For complete, runnable examples:

```json
{
  "name": "Customer Account",
  "assetCode": "BRL"
}
```

### Placement Rules:
1. Show the 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 to First Mention
Link concepts when first mentioned in a section:

> Each [Account](link) is linked to a single [Asset](link).

### Don't Over-Link
Don't link every mention of a term. Once per section is enough.

### Link Destinations

| Link Type | Destination |
|-----------|-------------|
| Concept name | Conceptual documentation |
| API action | API reference endpoint |
| "Learn more" | Deeper dive documentation |
| "See also" | Related but different topics |

---

## Page Length Guidelines

| Page Type | Target Length | 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 a page exceeds 5 screens, consider splitting into multiple pages.

---

## Quality Checklist

Before finalizing structure:

- [ ] Content is organized by user task, not system structure
- [ ] Overview pages link to all child content
- [ ] Section dividers separate major topics
- [ ] Headings create scannable structure
- [ ] Tables are used for comparable items
- [ ] Code examples follow explanations
- [ ] Cross-links connect related content
- [ ] Page length is appropriate for content type
- [ ] Navigation (prev/next) connects sequential content