Reading Flow Patterns

Reading flow patterns guide how users move through documentation. Good flow reduces cognitive load and helps readers find what they need faster.

The Inverted Pyramid

Structure content from general to specific—most important information first.

1. What it is — One-sentence definition
2. Why it matters — Use case or benefit
3. How to use it — Basic example
4. Deep details — Edge cases, options, advanced usage

Why This Works

• Scanners get the answer fast — No digging required
• Deep readers get context first — Understanding before details
• Page can be cut from bottom — Each layer is complete

Example

Before (buried answer):

## Authentication

There are several methods available for authenticating
with our API. Each method has trade-offs. OAuth 2.0
provides delegated access but requires more setup.
JWT tokens work for distributed systems. The most
common method is API key authentication.

After (inverted pyramid):

## Authentication

Use API key in the Authorization header:

    Authorization: Bearer YOUR_API_KEY

For delegated user access, use OAuth 2.0. For
distributed systems, use JWT. [Details below]

Entry Points

Multiple Starting Points

Users arrive from different contexts:

Design Each Page as a Landing Page

Every page should:

• State what it covers in the first paragraph
• Provide navigation to related content
• Work without requiring prior reading
• Give context for acronyms and terms

Information Scent

Users follow information scent—cues that predict what they’ll find if they click or read further.

Strong scent:

• Descriptive link text: “Configure OAuth authentication →”
• Meaningful headings: “Prerequisites for Production Deployment”
• Clear summaries: “This guide covers X, Y, and Z”

Weak scent:

• Generic links: “Click here”, “Read more”
• Vague headings: “Getting Started”, “Overview”
• No summaries: Page dives straight into details

Navigation Patterns

Horizontal Navigation (Breadth)

For exploring related topics:

• Next/Previous links
• Related topics sidebar
• “See also” sections
• Category/tag navigation

Vertical Navigation (Depth)

For exploring detail:

• Table of contents
• Child page links
• Expandable sections
• Anchor links to subsections

Context Before Action

Always provide context before asking the reader to act:

## Prerequisites

Before you begin, ensure you have:
- Node.js 18+
- API key ([get one here →](./api-key))
- 10 minutes

## Step 1: Install

Not:

## Step 1: Install

Run `npm install our-sdk`

(Reader wonders: Do I have the right Node version? Do I need an API key first?)

Flow Patterns by Document Type

Reading Flow Checklist

• First paragraph explains page purpose
• Inverted pyramid structure (answer first)
• Works as standalone entry point
• Clear navigation to related content
• Prerequisites before actions
• Strong information scent (descriptive links/headings)
• Obvious next steps

Sources

• Diátaxis Framework: Document type flow patterns
• Nielsen Norman Group: Information scent research
• Journalism: Inverted pyramid structure
• UX Research: Entry point and navigation studies