Explain the code

Written for version 0.1.14.

What it is for

Keeping the project’s website, README and ARCHITECTURE.md in step with the code. The website is how a clinician, a reviewer or the next person understands what the analysis does without reading R.

When to use it

  • A script has just joined the analysis (the main script now runs it) and needs its page.
  • Code changed and its page should say what it does now.
  • A page holds a pasted copy of code that may no longer match the script.
  • The site, README or architecture description needs repair.
  • An existing project site needs bringing up to the plugin’s current layout.
  • A decision was made, the plan was locked, or a new data source was added, and the plan needs updating to match.

What happens

Each definitive script is divided into labelled sections. Its page on the website shows those sections, imported from the script itself, so the code on the page is always the code that runs. Under each section the page explains, in plain language for a clinician:

  • what the step does and why;
  • what it takes in and where that comes from;
  • which part of the analysis plan it carries out;
  • what it hands on to the next step.

Abbreviations are defined, associations are not described as causes, and sources are cited from the project’s reference list. Where code and plan disagree, the page says so rather than smoothing it over.

The page and the sidebar are updated in the same pull request as the code change. The rendered site is either updated in the same pull request or published by a workflow, as the project chose.

What the website has

  • Home, then Clinical background and Methodological background: the general knowledge the methods rest on.
  • Study design and methods: what this study chose and why, in plain language. Notes say which part of the plan specifies each step, where the code doesn’t yet match the plan, and which choices are still open.
  • Code: one page per script, in the order the analysis runs them.
  • Project documents: the analysis plan, the architecture, AGENTS.md and the repository blueprint, shown from the files themselves so the site never holds an outdated copy.
  • About, and a page for addresses that don’t exist.

Each kind of page has its own icon and colour in the sidebar. Text that depends on a decision not yet made is highlighted in yellow, and the page says so at the top.

What it will not do

  • Run the analysis to build the website. Pages show code; results appear only from outputs already cleared for release.
  • Invent a citation. A statement that needs one it can’t find is flagged for the librarian reviewer.
  • Restyle an existing site without asking. It lists the differences from the plugin’s conventions first.

Ask it, for example

  • “Write the Quarto page for the script I just added to main.R.”
  • “This page has pasted code; switch it to import from the script.”
  • “Update ARCHITECTURE.md after this restructure.”
  • “Bring this site up to date with the plugin’s layout.”

Where the detail lives