The caption is the only part that travels

Assume it will be lifted

A figure in a programme report has a second life. It is screenshotted into a situation report, pasted into a cluster presentation, forwarded as an image, and reproduced in a donor update — every time without the paragraph above it.

Write for the second life. The caption is the only part of the analysis that travels with the picture, so it has to be self-contained.

Caption	What survives the paste
“GAM by commune”	The chart, with no interpretation
“Figure 3”	Nothing
“GAM by commune with 95% CIs. The three highlighted communes are the only ones whose interval clears the district median.”	The finding, the uncertainty and the limit

Four things a caption has to carry

The finding, as a sentence. Not what the chart shows — what it says. “Counting improved sources overstates coverage in every district” is a finding; “Improved source against basic service by district” is a file name.

The denominator, or where to find it. 1,955 households, 1,850 cases, 24 schools. A percentage with no denominator is a number a reader cannot weigh.

The uncertainty, if the chart has any. “with 95% confidence intervals” is four words and it stops the chart being read as twelve exact values.

What the chart does not support. One clause, and it is the one that gets removed first when someone edits for length. “The bars do not sum” or “the comparison is observational” or “a ranking of one commune against its neighbour is not supported”.

CAPTION = (
    "Four food security instruments applied to the same 1,955 households. "     # denominator
    "The highest prevalence is seven times the lowest, "                        # finding
    "so the instrument chosen decides the caseload before any analysis begins." # implication
)

labs(caption = str_wrap(CAPTION, 90))

The title and the caption do different jobs

A chart that has both should not say the same thing twice.

Element	Job	Length
Title	Names the comparison	3–6 words
Caption	States the finding and its limits	2–3 sentences
Axis label	Names the quantity and its unit	2–4 words
Direct label	Identifies a series in place	1–3 words

If the title states the finding, delete the caption or the title. Two headings competing is the commonest layout fault in a programme report, and the one that makes a page look busy without adding anything.

On this platform the title names and the caption tells. Every figure in build.py carries both, in both languages, and the split is enforced by the two fields being separate.

Labelling inside the chart

Four decisions that decide whether a reader has to look away from the data.

Direct labels beat legends. A legend makes the reader match a colour to a name and carry it back to the chart; a label at the end of the line does not.

for name, series in lines.items():
    ax.plot(series.index, series.values)
    ax.annotate(name, (series.index[-1], series.iloc[-1]),
                xytext=(6, 0), textcoords="offset points", va="center")

# ggrepel::geom_text_repel() on the last point of each series.

Label the values only when the reader needs them exactly. A bar chart with a value on every bar is a table wearing a chart’s clothes. Label the emphasised bars, or none.

Never label a value to more precision than the interval justifies. 42.9% on a bar whose interval is ±3 points, not 42.94%.

Put the unit on the axis, once. “Households flagged (%)” and then bare numbers, not “%” repeated on every tick.

Numbers in a bilingual caption

This platform ships every figure in two languages, and the caption is where the two diverge most.

caption={
    "en": "Counting improved sources overstates coverage in every district. "
          "The difference is households whose source is improved and more than "
          "thirty minutes away.",
    "fr": "Compter les sources améliorées surestime la couverture dans chaque "
          "district. L'écart correspond aux ménages dont la source est améliorée "
          "et située à plus de trente minutes.",
}

# One figure, two captions, written together rather than translated later.

The decimal separator changes — 42,9 % in French, 42.9% in English — and the renderer handles it, which is why the figure carries values rather than formatted strings.

The space before the percent sign changes too, and French uses a narrow no-break space. Get it from the formatter rather than typing it.

Translate the finding, not the words. A French caption that reads as a translation has failed the same test as a French lesson that does.

The five-second test

Show the figure and its caption to someone who was not in the analysis, and ask them what it says.

If they describe the chart, the caption is a title. “It’s a bar chart of communes” means the caption did no work.

If they state the finding, it works. “Three communes are clearly above the others” is the caption having done its job.

If they state a finding you did not make, fix the chart. A reader who says “so Dessalines is the safest” has read a ranking the intervals do not support, and the caption needs the clause that forecloses it.

Report it whole

Figure captions in this report

  Every figure caption states the finding as a sentence, names the
  denominator, and names one thing the figure does not support.

  Captions are written to be self-contained: a figure reproduced without its
  surrounding text should still carry its own interpretation and its own
  limits.

  Values are labelled to the precision the confidence interval supports and
  no further.

  Figures and captions exist in English and French. The captions are written
  in both languages rather than translated, so the finding rather than the
  wording is what is shared.

The second paragraph is the whole lesson, and it is a claim about the report’s own robustness rather than about its style.

What comes next

Everything so far has been about what the chart says. The next lesson is about the axis, where a chart can say something different from its own data without a single number being wrong.