Structural Patterns

Structural patterns form the skeleton of readable documentation. They determine how quickly readers can find information and how well they retain it.

Heading Hierarchy

The 3-Level Rule

Effective documentation rarely needs more than 3 heading levels:

• H2 — Major sections (concepts, features, APIs)
• H3 — Sub-sections (specific methods, use cases)
• H4 — Rarely needed (parameter groups, edge cases)

Quality Headings

Good headings are:

• Descriptive: “Prerequisites for OAuth Setup”
• Specific: “Configure Database Connection Pool”
• Action-oriented: “Deploy to Production”
• Scannable: Key info in first 2-3 words

Bad headings:

• Generic: “Overview”, “Introduction”, “Details”
• Vague: “Some Things to Know”
• Buried keywords: “A Few Notes About the Configuration Settings”

Front-Load Keywords

Users scan the left edge (F-pattern). Put keywords first:

• ✅ “Authentication: OAuth 2.0 vs API Keys”
• ❌ “A Comparison Between OAuth 2.0 and API Keys for Authentication”

Chunking

Chunking groups related content into digestible units. Working memory holds ~4 chunks—respect this limit.

Optimal Chunk Size

Chunking Long Lists

Before (9 items = overload):

## Configuration
- API key
- Base URL
- Timeout
- Retries
- Cache enabled
- Log level
- User agent
- Max connections
- SSL verify

After (3 chunks):

## Configuration

### Connection
- Base URL
- API key
- Timeout

### Reliability
- Retries
- Cache enabled
- Max connections

### Debugging
- Log level
- User agent
- SSL verify

Lists vs. Prose

When to Use Lists

• 3+ related items
• Steps in a sequence
• Options or choices
• Quick reference information
• Scannable content

When to Use Prose

• Explaining relationships between concepts
• Providing context or narrative
• Building understanding progressively
• Connecting cause and effect

Three List Types

Numbered lists: When sequence matters (steps, priorities, rankings)

Bulleted lists: When items are equal/parallel (features, requirements)

Description lists: When you have term-definition pairs (parameters, glossaries)

The Scan Pattern

Readers scan in F-patterns:

1. Read first heading fully
2. Scan subsequent headings
3. Read first sentence of relevant sections
4. Decide whether to commit

Design for scanning, not reading.

Structural Checklist

• No more than 3 heading levels
• Headings are descriptive (not “Overview”, “Details”)
• Keywords front-loaded in headings
• Paragraphs under 5 sentences
• Lists chunked to 3-7 items
• Clear H2 structure visible in outline
• Each section answers one question

Sources

• Google Developer Documentation Style Guide: Heading hierarchy recommendations
• Cognitive research: Working memory capacity (Cowan, ~4 chunks)
• Nielsen Norman Group: F-pattern scanning behavior