Cognitive Load

Cognitive load is the mental effort required to process information. Documentation that ignores cognitive limits feels “heavy” even when the content is simple. Understanding these limits helps create docs that readers can actually absorb.

The ~4 Chunk Limit

The Research

• Miller (1956): 7±2 items in short-term memory
• Cowan (2001): ~4 chunks in working memory

Why the difference? Miller measured rehearsal; Cowan measured active processing. Documentation requires active processing, so 4 chunks is your real limit.

Practical Implications

• Lists over 7 items need chunking (group into 2-3 sublists)
• Complex explanations need stepping stones (don’t jump to conclusion)
• Code examples need context (don’t assume they remember setup from 5 paragraphs ago)

Three Types of Cognitive Load

Intrinsic Load

What: Complexity inherent to the subject matter.

OAuth 2.0 has intrinsic complexity—multiple parties, token exchange, security considerations. You can’t simplify OAuth itself.

Strategy: Accept it. Focus on reducing other load types.

Extraneous Load

What: Mental effort wasted on poor presentation.

• Confusing navigation
• Inconsistent terminology
• Walls of text with no structure
• Critical info buried in paragraph 5

Strategy: Eliminate it. This is where documentation optimization makes the biggest impact.

Germane Load

What: Mental effort devoted to actual learning—connecting new concepts to existing knowledge.

Strategy: Facilitate it. Use analogies, build on prior knowledge, provide mental models.

The Formula

Total Capacity = Intrinsic + Extraneous + Germane

Goal: Minimize extraneous → Maximize germane

Chunking Strategies

Chunking groups related items into single mental units. 8 digits (2-0-2-5-1-1-1-8) becomes 1 date (2025-11-18).

Strategy 1: Hierarchical Grouping

Before (7 items = overload):

## Configuration
- API key
- Base URL
- Timeout
- Retries
- Cache enabled
- Log level
- User agent

After (3 chunks):

## Configuration

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

### Reliability
- Retries
- Cache enabled

### Debugging
- Log level
- User agent

Strategy 2: Sequential Phases

Before (9 steps = overwhelm):

1. Install dependencies
2. Create config file
3. Set API key
4. Initialize database
5. Run migrations
6. Start server
7. Test connection
8. Deploy to staging
9. Monitor logs

After (3 phases):

## Phase 1: Setup
1. Install dependencies
2. Create config file
3. Set API key

## Phase 2: Database
4. Initialize database
5. Run migrations
6. Test connection

## Phase 3: Deploy
7. Start server
8. Deploy to staging
9. Monitor logs

Strategy 3: Conceptual Grouping

Group by mental model, not by technical organization.

Before (organized by implementation):

- `AuthService.login()`
- `AuthService.logout()`
- `AuthService.refresh()`
- `UserService.getProfile()`
- `UserService.updateProfile()`

After (organized by user goal):

### Authentication
- Login: `AuthService.login()`
- Logout: `AuthService.logout()`
- Refresh: `AuthService.refresh()`

### User Management
- Get profile: `UserService.getProfile()`
- Update: `UserService.updateProfile()`

Reducing Extraneous Load

1. Consistent Terminology — Pick one term and stick with it. Don’t alternate between “API key”, “access token”, and “credentials” unless they mean different things.

2. Front-Load Critical Info — Don’t make readers search. Put the answer first, explanation second.

   High load:

   There are several considerations when choosing an authentication method, including security requirements, user experience, and implementation complexity. For most use cases, API keys provide the best balance.

   Low load:

   Use API keys for most use cases. Other methods (OAuth, JWT) are better for specific scenarios—see below.

3. Use Consistent Patterns — Same structure for same content types. If all API endpoints follow the same format, readers only need to learn the pattern once.

4. Remove Noise — Delete anything that doesn’t help the reader accomplish their goal. Hedging language, redundant explanations, obvious statements—all extraneous load.

Cognitive Load Checklist

• Lists chunked to 3-7 items per group
• Complex concepts broken into stepping stones
• Consistent terminology throughout
• Critical info front-loaded
• Repeated patterns for similar content
• No redundant explanations

Sources

• Sweller, J. (1988): Cognitive Load Theory
• Cowan, N. (2001): The magical number 4 in short-term memory
• Miller, G. (1956): The magical number seven, plus or minus two