Vignette structure and reproducibility
Vignettes tell an analysis story. References define the API. A reader should not have to distinguish a computed result from a proposed workflow by guessing.
The common shell
| Required role | Core notebook heading | Decision notebook heading |
|---|---|---|
| Question | Question | The decision |
| Grammar / pipeline | Pipe / Pipes | The analytical sentence |
| Plain-language interpretation | Analysis story and pipe commentary | Read it left to right |
| Analysis | Analysis story, Prepare and Figure | The missing information, code and figures |
| Result | What the figure tells us | What this does and does not tell us |
| Data used | Data used | Data used |
| Reproduce | Reproduce | Reproduce |
| See also | See also | See also |
These equivalent headings preserve narrative continuity while providing the
same jobs on every executable page. Notebook metadata records the mapping;
tests check it. The shared shell is generated by scripts/vignette_shell.py.
Scientific code and interpretation remain in the existing notebook builders.
Types of educational material
- Executable vignette: a supported notebook using a reviewed real fixture; execution and static-plot output are checked. Eight core notebooks and the Working Lands notebook currently meet this contract.
- Live-data recipe: code requiring provider access or optional dependencies. It is not an offline-certified result. Record the query and source revision when rerunning it; absence of live checks is not evidence of availability.
- Dependency design: a scientific question whose required nouns or verbs are missing. No computed result is presented. Decision Lab pages list the specific dependencies and publication gates.
- Method/collection page: conceptual explanation, a workflow directory, or a link to an external analysis artifact, not a claim of an executed notebook.
Adding a vignette
Write Question, Grammar / pipeline, Plain-language interpretation, Analysis, Result, Data used, Reproduce and See also sections. Use the shared shell for notebooks and link to canonical noun/verb pages. State the data provenance, environment, network requirements and validation status explicitly. Never fill a missing result with generated observations.
Keep the pipe short and put setup outside it. Show a plot of the result, then
explain what it does not establish. Use python scripts/run_vignettes.py
and mkdocs build --strict before publication.