Visual hierarchy uses typography, spacing, and formatting to communicate importance and structure. Good visual hierarchy makes documentation scannable.

Typography Patterns

Font Sizing

Establish clear visual distinction:

  • Headings — Noticeably larger than body text
  • Body — Comfortable reading size (16-18px)
  • Code — Same or slightly smaller than body
  • Metadata — Smaller, muted (timestamps, tags)

Font Weight

Use weight to signal importance:

  • Bold — Key terms, important warnings
  • Regular — Body content
  • Light — Secondary information (avoid for body text)

Whitespace

Breathing Room

Whitespace improves comprehension:

  • Between sections — At least 2x line height
  • Around code blocks — Clear separation from prose
  • Inside code — Consistent indentation, blank lines between logical blocks

The 60% Rule

Optimal content density: ~60% content, ~40% whitespace on the page.

Callouts

Callouts draw attention to specific information. Use them sparingly — too many diminishes their impact.

Callout Types

“Good documentation is like a well-organized toolbox — you can find what you need without thinking about where to look.”

Note
Use notes for additional context that supplements the main content. Background information, tips, or clarifications belong here.

Insight
Insight callouts highlight “aha moments” — key takeaways, surprising findings, or principles worth remembering. Use for positive reinforcement of important concepts.

Warning
Warnings flag potential issues, gotchas, or common mistakes. Readers should pay attention but can continue without immediate action.

Critical
Critical callouts are for escalation — data loss risks, security concerns, or breaking changes. Reserve for situations requiring immediate attention.

When to Use Each Type

TypeUse ForFrequency
QuoteHighlighted text, testimonials, principlesAs needed
NoteTips, background info, clarifications1-2 per section
InsightKey learnings, aha moments, summaries1 per major topic
WarningGotchas, common mistakes, deprecationsWhen relevant
CriticalData loss, security, breaking changesRarely

Guidelines

  • Sparingly: Maximum 1-2 callouts per page section
  • Concise: Keep to 1-3 sentences
  • Escalate appropriately: Most content → Note, few → Critical
  • Consistent titles: Use standard labels (Note, ★ Insight, Warning, Critical)
  • Don’t hide: Critical information shouldn’t only appear in callouts

Code Formatting

Inline vs. Block

  • Inline — Single commands, function names, variables
  • Block — Multi-line examples, configuration files

Code Block Best Practices

  • Include language identifier for syntax highlighting
  • Show realistic, runnable examples
  • Add comments for non-obvious lines
  • Keep under 20 lines (split if longer)

Visual Checklist

  • Clear heading size hierarchy
  • Consistent use of bold/emphasis
  • Adequate whitespace between sections
  • Callouts used sparingly
  • Code blocks with language hints
  • No wall-of-text sections

Deep Dives

01

Structural Patterns

Heading hierarchy, chunking, lists, and information architecture for documentation

02

Reading Flow Patterns

Progressive disclosure, entry points, and navigation for documentation

03 Here

Visual Hierarchy

Typography, whitespace, callouts, and code formatting patterns

04

Cognitive Load

Working memory limits, chunking strategies, and reducing mental overhead in documentation

05

Scannability

F-pattern optimization, the 60-second test, and making documentation instantly graspable

06

Progressive Disclosure

Layered information architecture, expandable sections, and showing depth on demand