Setting the file. One moment.
Subchapter 1.19
references/editorial-writing.mdMarkdown5 KBView on GitHub
How to write the text that frames a chart: titles, subtitles, source lines, and annotations. The text layer is what transforms a data display into a story.
Formula: State the insight in conversational language. The title is the takeaway, not a description of the chart.
| Good | Bad | Why |
|---|---|---|
| “Remote work doubled after 2020” | “Remote work percentage over time” | States the finding |
| “Big Tech roars back” | “FAANG stock performance” | Has editorial voice |
| “Austin is America’s fastest-growing city” | “City population growth rates” | Has a protagonist |
| “Q4 sales exceeded targets by 18%” | “Bar chart of sales” | Specific and falsifiable |
| “Women now outearn men in 3 metro areas” | “Gender pay gap data” | Surprising, newsworthy |
| “Renewables overtook coal in 2024” | “Energy source comparison” | Captures the inflection point |
The “one takeaway” test: If the reader looks at this chart for 5 seconds and walks away, what’s the one thing they remember? That should be the title. If the answer differs from what your title says, rewrite it.
Carry what the title can’t: units, time range, geographic scope, methodology notes.
"LI = low-income students") is better than a two-line subtitle with a dangling fragment.Examples:
Always include. Always format as “Source: Organization Name”.
| Do | Don’t |
|---|---|
| Source: Bureau of Labor Statistics | Data from BLS |
| Source: Company earnings reports | Source: https://sec.gov/filings/ (opens in a new tab)… |
| Source: World Bank, OECD | Source: Various |
No URLs (they’re not readable in a chart). No periods at the end. If multiple sources, separate with commas.
Avoid duplicating source attribution. If the chart spec includes chrome.source, that text renders inside the chart chrome. Don’t repeat the same source in a wrapper component’s caption or an adjacent paragraph. Use captions only for context not already in the chart (methodology notes, caveats).
Amanda Cox, editor of the NYT Upshot: “The annotation layer is the most important thing we do.”
Most charts need 0-3 annotations. If you need more, the chart is trying to tell too many stories. Split it into multiple charts or simplify the narrative.
| Annotate when… | Example |
|---|---|
| An outlier needs context | “Hurricane Katrina” on a damage cost spike |
| A trend changes direction | “Policy enacted” at the inflection point |
| Two series cross | “Overtook competitor in Q3” |
| A threshold is meaningful | Reference line at regulatory limit |
| The reader would ask “what happened here?” | Any visible anomaly that begs explanation |
Short noun phrases or fragments, not full sentences.
| Good | Bad |
|---|---|
| “Pandemic lockdowns” | “This is when pandemic lockdowns began” |
| “Fed rate hike” | “The Federal Reserve raised interest rates” |
| “IPO” | “The company went public on this date” |
Use \n for multi-line annotations when context requires more than a few words, but keep each line to 4-8 words.
| Information type | Placement |
|---|---|
| Units, time range, scope | Subtitle |
| Specific data point callout | Annotation |
| Methodology caveat | Footer |
| Data recency warning | Subtitle |
| Overall narrative framing | Title |
| “What happened here?” context | Annotation |