Unit 08.02: The prose and the code in one file

A report where the numbers are typed in will be wrong within one revision of the data.

The prose and the code live in one file

A Quarto document is a plain text file with a YAML header, prose in Markdown, and code chunks that run when the document is rendered. The output is a fresh HTML, PDF or Word file every time.

The point is that numbers in the text come from inline expressions rather than from typing. Re-render after a data revision and the sentences, the tables and the charts all update together. Nothing can drift out of step, because nothing was copied.

echo: false in the header hides the code from readers who want the findings, while it stays in the file for anyone who wants to check the work. And a Limitations section is not optional — it is where the constraints you found during cleaning finally reach the reader.

This block writes a small report file and reports its structure.

# A Quarto document is a text file. This writes one and shows its structure.
qmd <- c(
  "---",
  "title: Ward visit rates, January to March 2026",
  "format: html",
  "execute:",
  "  echo: false",       # readers see results, not code
  "  warning: false",
  "---",
  "",
  "## What this report answers",
  "",
  "Which wards recorded the highest visit rates, over what period.",
  "",
  "

The document is 24 lines. The front matter ends at line 7, giving format and execution options. There are three sections — what the report answers, findings, limitations — and 1 code chunk. The finding sentence contains an inline expression rather than a typed number, which is the mechanism the whole approach rests on.

The mistake this prevents

The mistake is rendering once and then editing the output file. The next render overwrites the edit, and in the meantime the source and the published document disagree.

Takeaway

Put the code and the prose in one Quarto file, use inline expressions for every number in the text, hide code with echo: false for non-technical readers, and always include a Limitations section.

Mark complete