Visual Writing

Parent: Writing and Documentation · researched 2026-05-29T19:22:17.726Z· 7 sources · 9 concepts · skill visual-writing

Reference for the words that ship with images, charts, and infographics: alt text, captions, chart titles, axis labels, and annotations. The image is half the message. This skill is the other half.

Visual Writing

Reference for the words that ship with images, charts, and infographics: alt text, captions, chart titles, axis labels, and annotations. The image is half the message. This skill is the other half. [source]

The one rule: visual writing makes images legible without the image

Every other rule in this skill follows from one premise: a reader who cannot see the image must still receive the load-bearing information. That reader may be a blind user with a screen reader, a sighted user on a slow network, a sighted user skimming for the chart's takeaway, or a search engine indexing the page. [source]
The alt text serves the screen reader. [source]
The caption serves the skimmer. [source]
The chart title serves the takeaway. [source]
The annotation serves the trend. [source]
They are four jobs, not one. [source]

Core concept 1 — The alt-text triple

Alt text answers three questions: [source]
What's there? - concrete, observable content [source]
Why is it there? - the function the image serves in the page [source]
What does it show? - the specific information a sighted reader gets [source]

Core concept 3 — Caption vs alt text vs long description

Alt text is for users who cannot see the image. It lives in alt="". Typically 5 to 15 words. [source]
Caption is visible to everyone. It lives in <figcaption>. Adds context, attribution. [source]
Long description is a structured prose alternative for complex images. [source]
Anti-pattern: duplication. If alt="Sales rose 18% in Q4" and the caption reads the same, the screen-reader user hears it twice. [source]

Core concept 4 — Tufte's principles

Above all else, show the data. Title and labels exist to disclose the data. [source]
Maximize the data-ink ratio. Erase ink that doesn't carry data. [source]
Erase redundant data-ink. A bar chart with a legend, title, axis labels, and a redundant data table embeds the same fact four times. [source]
Reject chartjunk. Heavy gridlines, moiré fills, 3-D effects, drop shadows. [source]
Use sparklines for in-line trend. Caption a sparkline like a word - usually with just the latest value. [source]

Core concept 5 — The Knaflic "action title" rule

The chart title states the takeaway. The axis labels confirm it. [source]
Generic title (descriptive only): [source]
> Quarterly Revenue, 2023–2024 [source]
Action title (takeaway-bearing): [source]
> Q4 2024 revenue exceeded plan by 18% - the strongest quarter on record [source]
Rule of thumb: no chart without a takeaway. If you cannot state in one sentence what the chart is for, either find the takeaway or delete the chart. [source]

Core concept 6 — Axis labels

Label the units. "Revenue (USD millions)" not "Revenue." [source]
Date axes get human dates. "Jan 2024" - not raw timestamps, not "Q1". [source]
Avoid axis label rotation. If labels overflow horizontally, the chart probably has too many categories. [source]

Core concept 7 — Annotations

An annotation is a written assertion attached to a specific data point. Use annotations for: [source]
The single highest or lowest point ("peak: 8,420 - Aug 14") [source]
A regime change ("← deploy of v2.3") [source]
An anomaly ("backfill artifact; ignore") [source]
Annotations are journalism inside a chart. Empty annotations ("note this") are wasted ink. [source]

Core concept 8 — Accessible data-viz captioning

The "describe the trend, then the value" pattern: [source]
> Sales increased steadily from January to July, then declined through December. The peak was 8,420 units in July. The lowest month was December at 3,100 units. [source]
Anti-pattern: read every value. [source]
> January was 4,200, February was 4,800, March was 5,100... [source]
If every value matters, provide a <table> and skip the chart alt-text recital. [source]

References

W3C WAI: Images Tutorial and Alt Decision Tree [source]
Edward Tufte, The Visual Display of Quantitative Information (2nd ed., 2001) [source]
Cole Nussbaumer Knaflic, Storytelling with Data (2015) [source]
UK GDS: Text descriptions for data visualisations [source]
WCAG 2.1, Success Criterion 1.1.1 (Non-text Content) [source]

Children

Alt-Text (Decorative/Informational/Functional/Complex) (frontier)
Image and Photo Captions (frontier)
Video Captions and Sub-Captions (frontier)
Chart Titles and Axis Labels (frontier)
Data-Viz Annotations (frontier)
Edward Tufte Principles (data-ink ratio, chartjunk) (frontier)
Cole Nussbaumer Knaflic Action Title Rule (frontier)
Infographic Copy (frontier)
Pull Quotes and Callouts (frontier)

Frontier under this node: Alt-Text (Decorative/Informational/Functional/Complex), Chart Titles and Axis Labels, Cole Nussbaumer Knaflic Action Title Rule, Data-Viz Annotations, Edward Tufte Principles (data-ink ratio, chartjunk), Image and Photo Captions, Infographic Copy, Pull Quotes and Callouts, Video Captions and Sub-Captions

← the whole tree · 3D view· how to read this page