Scannability

Most readers don’t read documentation—they scan it. Understanding scan patterns lets you design docs that work with human behavior instead of against it.

The F-Pattern

Eye-tracking reveals a consistent scan pattern shaped like the letter F:

1. Top horizontal bar — Users sweep across the top first
2. Second horizontal bar — Shorter sweep, lower on page
3. Left vertical stem — Scan down the left edge, looking for hooks

What This Means

• Top 30% of your page gets the most attention
• Left edge of each line gets scanned
• First 2 words of each line get disproportionate attention

Front-Loading

Put the most important information first—in paragraphs, in lists, in headings.

Before (Buried Info)

## Authentication

There are several methods available for authenticating
with our API. Each method has different use cases and
trade-offs you should consider. The most common method
used by developers is API key authentication.

After (Front-Loaded)

## Authentication

Use API key in the Authorization header:

    Authorization: Bearer YOUR_API_KEY

Other methods: OAuth 2.0, JWT tokens [details below]

The scanner gets the answer immediately. Details follow for those who need them.

Optimize the Left Edge

Keywords at the start of lines, not buried in the middle.

Before (Keywords Buried)

- You can authenticate using OAuth
- In case you need JWT tokens, there's an endpoint
- For API keys, visit the dashboard

After (Keywords First)

- **OAuth:** Full authorization flow
- **JWT:** Stateless token authentication
- **API key:** Simple header-based auth

Scanners see OAuth, JWT, API key immediately.

First 2 Words Count

Research shows the first 2 words of each line receive disproportionate attention.

Headings

• ✅ “Configure database connection”
• ❌ “How to go about configuring your database”

List Items

• ✅ “API key — Simple authentication”
• ❌ “Use this for simple authentication: API key”

Links

• ✅ Authentication guide →
• ❌ Click here for authentication

The 60-Second Test

Can a reader grasp main points in 60 seconds without deep reading?

What Readers Should Know in 60 Seconds

1. What is this? — Topic and purpose
2. Is this relevant? — Audience and use case
3. What can I do? — Outcomes and actions
4. Where do I start? — Clear entry point

Components of 60-Second Scannability

Scannable title:

# Quick Start: Your First API Request

One-sentence summary:

Get up and running with our API in 5 minutes.

Quick ToC:

**In this guide:**
1. Get API key
2. Install library
3. Make request

Visual hierarchy: Headings, lists, code blocks, callouts—all provide scan hooks.

Descriptive Headings

Generic headings force readers to read content. Descriptive headings let them skip to what matters.

Low Scannability (Generic)

# Overview
# Details
# Additional Information
# Notes

Reader learns nothing. Must read everything.

High Scannability (Descriptive)

# What is OAuth 2.0?
# Configure API Keys
# Common Authentication Errors
# When to Use JWT vs OAuth

Reader can jump directly to their question.

Headlines Must Earn Their Place

Every headline appears in the Table of Contents. Structure for structure’s sake hurts reading flow.

Before adding a headline, ask:

1. Would someone jump directly to this from TOC?
2. Is this a standalone thought worth bookmarking?
3. Does this help scanners find what they need?

If NO to all three → Don’t use a headline. Use inline structure instead:

• Bold text for emphasis within flow
• Callouts for insights, warnings, key info
• Lists for multiple related items
• Paragraphs for connected thoughts

The Anti-Pattern:

❌ WRONG - Headline for every sub-point:
## Authentication
### Overview
### How It Works
### Configuration
### Examples

✅ CORRECT - Flow with inline structure:
## Authentication

Authentication uses API keys. **Configuration:** Set `API_KEY`...

❌ WRONG - H3 per list item (wastes screens):
### Module 1: Foundations
Description paragraph...

### Module 2: Quality
Description paragraph...

✅ CORRECT - Actual list:
## Module Key Insights

1. **Foundations** — You're engineering context, not prompts.
2. **Quality** — AI produces what you tolerate.

Rules:

• 4+ similar items → LIST, not sections
• If it doesn’t deserve TOC space, it doesn’t deserve a headline
• Fewer headlines = better reading flow
• When in doubt, use bold or a callout

Scannability Checklist

• Critical info in top 30% of page
• Keywords at start of lines and list items
• First 2 words meaningful in each heading
• Page passes 60-second test
• No generic headings (“Overview”, “Details”)
• Link text describes destination
• Similar items in lists, not H3 sections (4+ items rule)

Sources

• Nielsen Norman Group: F-pattern eye-tracking studies (232 users)
• Web usability research: First 2 words attention studies
• Technical writing guides: Google, Microsoft front-loading recommendations