← Files DataARCHIVED FILE

shared/data-writing.md

2.94 KB · Nov 19, 2026 · 00:12 UTC

↓ Download file

See the change to this file →

# Writing about data

Apply to inline answers, reports, dashboards and chart copy. Read once when composing substantive analytical text and reuse across surfaces; brief answers and simple file handoffs need no extra read. Keep the analytical depth, evidence and requested detail.

- **Answer first.** Lead with the strongest supported answer and the evidence that makes it useful. A short answer needs no summary section; the report workflow owns substantial report openings.
- **Use plain language.** Name the people, product or behavior and use direct verbs, including in summaries. Replace broad analytical labels with what changed: “More visits came from first-time buyers, who buy less often” rather than “an unfavorable mix shift.” Prefer “People installed the feature but have not used it” to “Activation opportunity.” Remove inflated language and filler such as “The data reveals several key insights.”
- **Make numbers informative.** Give consequential figures their comparison, period, population and units. State both endpoints and the absolute difference for a change; preserve them when shortening the finding. Distinguish percentages from percentage points. Explain the pattern or implication instead of narrating every chart value.
- **Match claims to evidence.** Separate findings, hypotheses and recommendations. “This is explained by…” fits an established explanation; “This may be explained by…” fits a hypothesis. An arithmetic contribution alone does not establish a cause. Describe modeled gains as conditional; identifying a problem does not establish that a proposed remedy will work.
- **Make the argument easy to scan.** Use short paragraphs and parallel bullets; bold short lead-ins and decisive comparisons, not entire sentences. Labels such as **Why:** or **Next:** can clarify the argument; they are not a required template. For example: “**Why:** Mobile address validation is the leading hypothesis.”
- **Round for the reader.** Use consistent precision that preserves meaningful differences and threshold crossings. Calculate with unrounded values; show exact values when they matter. Compact large counts when useful (24.5k, 1.2M), not dates, IDs or percentage-point changes.
- **Put material limitations beside the claim.** Explain the specific uncertainty and its consequence once. Keep detailed methods and provenance inspectable, bringing them into the main text when requested or needed to interpret the result. Preserve relevant statistical uncertainty; remove generic disclaimers and invented confidence ratings.
- **Cut repetition and decoration.** Avoid repeating a takeaway across the title, summary, metric cards and prose. Remove process narration, obvious annotations and generic recommendations. A useful next step names a concrete action and its basis; do not invent an owner, decision or commitment.

Before delivering, remove anything that neither answers the question, supports a finding nor changes interpretation or action.

SHA-256: c5cf2222f872e4566b16887430e1434ee2e1420daa5c8c9ffffa13420c990431