Climate-Smart Public Health (CSPH) is a data-driven approach to detect, quantify, and adapt to climate-related health impacts at a global scale, with efforts spanning surveillance, risk assessment, early warning and response, and healthcare systems adaptation [@goldenClimatesmartPublicHealth2025]. In practice, CSPH depends on complex computational workflows that integrate heterogeneous climate, environmental, and health data and that must remain understandable, reproducible, and adaptable across collaborators and local settings.
Despite the central role of these workflows in academia and industry, effective, reproducible documentation remains an overlooked and under-served part of delivering high quality software [@aghajaniSoftwareDocumentationIssues2019]. This issue is likely to become more acute as software development continues to expand in scale and complexity [@GithubInnovationGraph; @martinelliSoftwareHeritageActivity2026] and as the volume and sophistication of AI generated code submitted to public repositories continues to increase [@robbesAgenticMuchAdoption2026]. Developers therefore need solutions beyond traditional static documentation to support workflow execution, verification, and reproducibility, in practical and user-friendly ways.
Conventional documentation can describe a workflow, but for complex, multi-step, order-dependent tasks and projects, it is often insufficient at capturing and verifying critical runtime execution details such as platform dependencies, configuration, versions, and relationships between steps [@ebertGeneralConceptConsistent2015]. Command-line interface (CLI) wrappers can improve automation and reproducibility of a declarative workflow by providing a directly executable interface for complex tasks [@vanderaalstDeclarativeWorkflowsBalancing2009]. However, developing and maintaining CLI wrappers can be time-consuming and introduces a persistent trade-off between control and flexibility: highly specialized wrappers can improve consistency, but may be inflexible and difficult to maintain, while more generic wrappers enable complexity by shifting the burden to the user through large numbers of flags and configuration options [@sadiqSpecificationValidationProcess2005; @brackTenSimpleRules2022]. Lastly, AI and agentic systems are promising, but their reproducibility remains limited by non-determinism [@siddiqLargeLanguageModels2025]. Furthermore, current practical agentic workflow implementations (such as harnesses) still require careful human oversight to achieve acceptable reliability [@agrawalCanAIConduct2026].
Executable literate programming approaches can encode and enforce complex
workflow steps and generate idempotent results. Quarto is a modern, plain-text,
multi-language, and multi-output literate programming framework for creating
reproducible documents and workflows [@allaireQuarto2026]. Building on Quarto with a
carefully designed set of templates and extensions, we introduce Quarto Manuals, a
framework for executable software manuals that guide users through a workflow as ordered, interactive
pages that combine explanation, code execution, and verification. Rather than
hiding workflow decisions and steps, Quarto Manuals keep them visible and editable,
making them ideal for research computing contexts where local constraints and
expert judgment often shape execution parameters. The framework is powered
by quarto-emit, a lightweight backend extension that materializes conventional
workflow artifacts from manual pages when needed. We demonstrate the approach
with three examples of increasing sophistication: a simple manual for
staging datasets in your project space; an intermediate manual for geospatial
aggregation of environmental exposure data; and a complex manual for creating
robust, reproducible, fully containerized geospatial data science
environments on High Performance Computing (HPC) clusters. All examples are available at the project website.
For authors, Quarto Manuals provide a structured yet adaptable way to turn recurring workflows into reusable operators' manuals for themselves and colleagues; for operators, they provide a stepwise, testable process for generating reproducible setup and execution artifacts and confirming progress throughout execution in a structured and auditable manner.
Quarto Manuals promise to improve the reproducibility and reliability of scientific workflows — particularly in contexts like CSPH where local constraints and expert judgment shape execution parameters and conditions — while also providing an accessible and interactive experience for users. In future work, we hope to explore how Quarto Manuals may be used in conjunction with the increasing adoption of AI and agentic systems in software development to provide a framework for ensuring that scientific workflows remain transparent, verifiable, and reproducible in the face of increasing complexity and non-determinism.
- abstract as prose
- give the examples an onramp to users to "get started now!"
- visual abstract/diagram
- stylize each block so it is visually distinct
- use Lua to print out useful render messages when blocks are being processed
- negative reinforcement: identify and correct misuse of the manual visually
- setup a testing suite in a separate repo
- can Lua be used to connect checks and prereqs across pages? Maybe?