# Lecture and slide authoring conventions

Rules for writing lecture notes, slides and teaching pages in any Morrison-Lab course repository.
They come from Ezra's directions for DATA 571, recorded in the private `Morrison-Lab/lds` repository's `AUTHORING.md`, and apply to every course site.
The prose wording of each rule is canonical in [psw's "Writing for teaching" chapter](https://github.com/Morrison-Lab/psw/blob/main/chapters/teaching.qmd), which also carries the examples.
This fragment is the agent-facing copy: follow the rules, and link to psw instead of restating its text.

## Structure

- **Build the lecture from exercise and solution pairs.**
  Pose each data manipulation, analysis, calculation, derivation or proof in an `#exr-` div, and put the worked answer in the repository's solution div (`::: solution` or the `.sol` class), with a `#sol-` id sharing the exercise's slug.
  [`quarto-divs-for-typed-content`](quarto-divs-for-typed-content.md) defines the solution div, and a repository uses the syntax its own `student-qmd` setup expects.
- **Put a slide break between an exercise and its solution** (`{{< slidebreak >}}`, never `---`), so the prompt is on screen alone while students work.
- **Ask before defining and before stating a result.**
  Precede every `#def-` div, and every result div (`#thm-`, `#lem-`, `#cor-`, or `#prp-`) that you add or edit, with an exercise that asks the question the div answers.
  The solution answers informally, and the formal div follows the solution div, never inside it.
  [`informal-definitions`](informal-definitions.md) states the underlying rule.
- **Cite result divs, never solutions** (Ezra, 2026-10-26).
  A proof or any later argument cross-references a result div (`@thm-`, `@lem-`, `@cor-`, or `@prp-`) and never a solution (`@sol-`).
  When a later argument relies on a solution, add a result div that states the claim after that solution, and cite the result div.
  The one exception is an exercise that asks students to prove a result before the result is stated: the result's proof may cite the solution that precedes the result.
  Put `<!-- check-solution-citations: allow -->` on the same line as the `@sol-` cross-reference.
  The [`check-solution-citations`](https://github.com/Morrison-Lab/gha/blob/main/website/reference/check-solution-citations.qmd) workflow in `Morrison-Lab/gha` enforces the citation rule, and the section [Cite results, not solutions](https://github.com/Morrison-Lab/psw/blob/main/chapters/mathematical-writing.qmd#cite-results-not-solutions) in psw is canonical.
- **One bottom-level prompt per exercise.**
  Do not write one exercise with parts (a) through (e).
- **Put on a slide only what the audience should look at.**
  Put examples and short commentary in `#exm-` and `#rem-` divs, because a `::: notes` div is unboxed plain text on the web page.
- **Put a long paragraph of commentary in `::: {#rem-name .remark .notes}`.**
  It is speaker notes on the slides and a boxed remark on the web page, which attendees who missed the lecture read, so nothing is lost or said twice.
  Add a separate short `#rem-` box only when the slide needs a takeaway to look at.
  [`quarto-remarks-vs-callouts`](quarto-remarks-vs-callouts.md) says what belongs in a remark.
- **Subfiles hold one unit each and start with no heading.**
  The chapter file is a spine of headings, slide breaks and `{{< include >}}` calls.
  Name each unit's file `_<stem>_<type>.qmd`, with the div type last (`_def`, `_exr`, `_sol`, `_thm`, `_exm`, `_fig`, `_rem`).
  The files of one idea then share a stem and sort together:
  `_backfitting-update_def.qmd`, `_backfitting-update_exr.qmd` and `_backfitting-update_sol.qmd` (Ezra, 2026-10-18).
  The type follows an underscore because stems are kebab-case, so an underscore never occurs inside a stem.
  Decompose further when it is a judgment call.
  New and revised content gets one div per subfile, a solution in its own `_sol` file included (Ezra, 2026-10-18).
  Existing files keep their `_def-` style prefix names until a separate rename sweep.
  A subfile that is not otherwise touched keeps its present layout.
- **Never nest one theorem-type div inside another.**
  A special case gets its own div after the general one and links to it.
- **Keep body text off section and title slides.**
  Reveal.js does not scroll them, so put a slide break after the heading.

## Content

- **State the notation, and name the alternatives** a reader will meet in other sources, in the definition div or a callout beside it.
- **Name synonyms and near-synonyms** where a term is defined, and say which one the notes use.
  Put every alias in the `#def-` div title, as in "Risk (expected loss, population risk, true risk, generalization error, expected prediction error)", and bold each alias where the definition names it, including the name another source uses, such as a textbook's (Ezra, 2026-10-15).
  The rule holds in every repository, including `mds`, `pds`, `sds`, `lds` and `rme`.
  The wording is canonical in psw's "Defining terms clearly" chapter.
- **Use real data and compute every number.**
  Never type or paste output.
  See [`hypothetical-examples`](hypothetical-examples.md).
  The rule holds in every notes repository (`mds`, `pds`, `sds`, `mcs`, `lds`, `rme`), not only in lds, whose `CLAUDE.md` first stated it.
  A typed number goes stale when the data or the code changes, and nothing on the page shows that it did.
  The wording is canonical in psw's "Writing for teaching" chapter, and gha's `check-typed-output` flags a comment in a code chunk that stands in for a printed value (`# ->`, `#>`).
  - **Do:** run the code in an executable chunk, and take each number in the prose from inline code.
  - **Don't:** type the result as a comment under the code, or write a computed value into a sentence by hand.
- **Give every topic an applied example on real data and at least one figure.**
  This holds for lectures and for the prerequisite sites (`mds`, `pds`, `sds`), not only for one deck.
  Do not leave a page that is only definitions and algebra.
  The wording is canonical in psw's "Show each idea applied and in a figure".
- **Follow every abstract div with its own concrete `#exm-` div.**
  This covers each definition, theorem, lemma, corollary and any other abstract div (Ezra, 2026-10-08).
  Place the example directly after the div it illustrates.
  A related theorem or corollary does not exempt the definition: the definition still gets its own example, and so does the theorem.
  The rule holds in every repository, including `mds`, `pds`, `sds`, `lds` and `rme`.
- **Keep only the definition in a `#def-` div.**
  Put the properties of the defined object in a separate `#thm-`, `#lem-` or `#prp-` div after it, with a proof where one is known (Ezra, 2026-10-09).
  The rule holds in every repository, including `mds`, `pds`, `sds`, `lds` and `rme`.
  The wording is canonical in psw's "Writing for teaching" chapter.
- **Define one term per `#def-` div.**
  Never combine two terms, such as a population and its distribution, in one definition (Ezra, 2026-10-12).
  Give each term its own div and its own id, and let the second link to the first.
- **Define an object at the most general level that covers every case.**
  Define a distribution by its probability measure, not its CDF, density or mass function, which exist only in some cases (Ezra, 2026-10-12).
  Put the special cases in a remark after the definition.
  Write a count as math, such as `\abs{\set{u \in U : X(u) \in A}}`, not as words inside `\text{}`.
- **Present R results with modern packages, even for a base R fit.**
  A model fit with `lm()` or `glm()` shows its coefficients through `parameters::parameters() |> print_md()` or `gtsummary::tbl_regression()`, never a `summary()` or `coef(summary())` printout (Ezra, 2026-10-09).
  Figures use ggplot2, with sjPlot or ggeffects for prediction plots and `performance::check_model()` for diagnostics, never base graphics (`plot()`, `lines()`, `abline()`).
  Avoid ggfortify's `autoplot()` for `lm` fits: it warns that `fortify(<lm>)` is deprecated.
  Reading a single value out of a fit for inline code (`coef(fit)[["x"]]`) is fine;
  the rule is about what the reader sees.
  Add each package to the repository's render dependencies in the same PR.
  Ezra's `rme` notes show the patterns;
  the wording is canonical in psw's "Present R results with modern packages".
- **Use dplyr over base R for data manipulation.**
  Select columns with `dplyr::select()`, filter rows with `filter()`, add columns with `mutate()`, drop missing rows with `tidyr::drop_na()`, stack data frames with `bind_rows()` and build them with `tibble::tibble()`, chained with `|>`.
  Never write `df[, cols]`, `df[df$x > 0, ]`, `subset()`, `df$new <- ...`, `complete.cases()`, `rbind()` on data frames, or `data.frame()` (Ezra, 2026-10-09).
  Indexing a matrix or vector, and reading one value for inline code, is fine.
  The wording is canonical in psw's "Manipulate data with dplyr, not base R".
- **Cross-reference only what the reader has already seen.**
  Never point to a figure, table, equation or result that appears later (Ezra, 2026-10-08).
  Put a figure directly after the sentence that refers to it, and make the example that shows the figure, not an earlier definition, refer to it.
  See [`forward-references`](forward-references.md).
- **Put media links beside the content they support.**
  See [`media-links-beside-content`](media-links-beside-content.md).
- **Place each topic in the earliest course site whose readers need it.**
  See [`course-sequence`](course-sequence.md).
- **Do not answer graded work in student-facing notes.**
  Check the grading repository before writing a solution, and use a different example when an exercise is graded.
- **Never name a private repository or its paths on a student-facing page, not even in an HTML comment.**
  Pandoc copies an HTML comment into the rendered HTML, so the published page source carries it.
  Keep such a note in an unrendered file beside the page's subfiles, such as a `README.md`.
  Measured on Morrison-Lab/mcs#168 (2026-11-13): a comment that named the grading repository and the quiz's path shipped on the public page, fixed in Morrison-Lab/mcs#169.
  - **Do:** write "the graded week-1 quiz" in the comment, or move the note to an unrendered README.
  - **Don't:** write the private repository's `owner/name` or file path in a `<!-- -->` comment on a page.

## Prose

Write plain, literal sentences with one idea each.
State the claim instead of using an idiom, name the referent instead of using a bare "this" or "there", and never write "thing".
Cut AI clichés: straw objections, personified abstractions, colon reveals, answered rhetorical questions and closing aphorisms.
The detailed rules are in [`plain-prose`](plain-prose.md), [`ai-tells`](ai-tells.md) and [`ambiguous-reference`](ambiguous-reference.md), and psw's [Writing for teaching](https://github.com/Morrison-Lab/psw/blob/main/chapters/teaching.qmd) chapter.

## Related

- [`definition-crossrefs`](definition-crossrefs.md), [`informal-definitions`](informal-definitions.md), [`forward-references`](forward-references.md), [`semantic-line-breaks`](semantic-line-breaks.md)
- [`notes-content-rules`](notes-content-rules.md): state the estimand, link prerequisite definitions, talk about ideas not the notes.
- [`quarto-divs-for-typed-content`](quarto-divs-for-typed-content.md): which div type holds which content.
- [`quarto-revealjs-div-styling`](quarto-revealjs-div-styling.md): style div boxes on slides as on the web page.
