Technical Guideline Series

TEMPLATE - How To Author a Technical Guideline

Authors

Affiliation

Rainer M. Krug

Senckenberg

Renske Gudde

Senckenberg

Abstract

TO BE ADDED

General

This template repository is designed to be cloned or instantiated through GitHub’s “Use this template” flow. It contains:

• A single Quarto document (TG.qmd) that holds both the guidance text and the technical content of the guideline.
• Utility scripts in scripts/ used locally and by the GitHub Actions workflow.
• A publishing workflow that turns TG.qmd into a static site on the gh-pages branch.

Recommended branch model when converting this template into a working TG:

• dev – Working branch for day-to-day authoring. Open pull requests against main from here.
• main – Source of truth. Merging into main triggers the build-and-publish workflow.
• gh-pages – Deployment branch managed entirely by CI. Do not edit this branch manually.

How to use this template

1. Create a new repository from the template and clone it locally.
2. Configure repository secrets (if any) and ensure GitHub Pages is set to build from gh-pages.
3. Update the YAML front matter in TG.qmd (see below) and replace every placeholder highlighted as TO BE ADDED or similar.
4. Draft the content directly in TG.qmd, replacing the instructional paragraphs with your guideline-specific text.
5. Preview locally with quarto render TG.qmd --to html. If you enable code execution, run bash scripts/detect_r_packages.sh TG.qmd to confirm dependencies are listed.
6. Commit changes, open a pull request against main, and merge once reviewed. The GitHub workflow will publish index.html to gh-pages automatically.

Document skeleton

The sections below are intentionally short so you can overwrite them with your actual content:

• Purpose – Explain what the TG addresses and why it matters for IPBES teams. Replace the sample sentence with a concise summary.
• What and Why – Describe the objective, scope, and expected outcomes. Include definitions or context needed for new readers.
• Inputs and Assumptions – List data sources, prerequisites, external tools, and any assumptions the method depends on.
• Steps – Provide the reproducible workflow. Break it into numbered subsections, include code chunks where relevant, and highlight decision points or alternatives.

Feel free to introduce additional headings (Background, Case Study, Appendix, etc.) as long as the document remains easy to navigate with the generated table of contents.

Metadata in YAML front matter

Keep the YAML block at the top of this document accurate and machine-readable. Pay special attention to:

• subtitle – Provide the human-readable TG title (e.g. “Part 6 – How to Upload to and Download from Zenodo”).
• author – List all contributors. Each entry can include nested name (with family and given), id, orcid, email, affiliation, and roles. Remove placeholder information when you add your own.
• abstract – Supply a two- to three-sentence synopsis. This text appears in the global TG directory.
• keyword – Provide a short list of search terms. Use lowercase words without spaces (replace with hyphen if needed).
• categories – Combine audience tags (expert, tsu, secretariat, assesment_tsu, assesment_experts) with topical tags (for example data, modelling, literature, tools, r, template, …). These audience tags drive icon rendering in the directory.
• license – Default is CC BY. Update if the TG requires a different Creative Commons licence.
• citation and doi – Update with the final DOI minted via Zenodo. Quarto currently requires the DOI both inside citation and at the top level.
• version – Bump the version whenever content changes materially. Follow semantic versioning (major.minor.patch) where practical.
• date – Use either a fixed ISO date (2024-05-17) or last-modified to have Quarto fill it during rendering.
• execute.eval – Leave false unless you need runtime evaluation. When set to true, CI installs and runs the detected R packages.

Branching and publishing workflow

The GitHub Actions pipeline (.github/workflows/quarto-gh-pages.yml) performs the following steps whenever main changes or you trigger it manually:

1. Detect R usage via scripts/detect_r_packages.sh. If no R code is found, CI skips the R toolchain.
2. Export the YAML front matter into metadata_qmd.yaml for downstream indexing.
3. Install Quarto (and, when required, R plus the packages listed in R.pkgs).
4. Render TG.qmd to index.html.
5. Copy index.html, metadata_qmd.yaml, and any R.pkgs manifest into public/ and publish that directory to gh-pages using the peaceiris/actions-gh-pages action.

You can reproduce these steps locally if you want to vet the output before pushing.

Working with code chunks

• Use Quarto chunk options with the #| prefix to control behaviour (#| label:, #| eval:, #| echo:).
• Keep chunk labels unique and descriptive (load_data, fig_regions, …) to assist with debugging and cross-referencing.
• Group related logic into short chunks; long analyses should be split into manageable sections.
• Suppress noisy console output with #| message: false and #| warning: false where appropriate.

Example chunk:

library(sf)
library(ggplot2)

Evaluation policy

• Global evaluation is controlled by the execute.eval value in the YAML front matter. Leave it as false when you want to ship narrative-only guidance or code snippets that readers run locally.
• To execute specific chunks even when the global setting is false, set #| eval: true on that chunk. Conversely, when the global setting is true, disable individual chunks with #| eval: false.

# placeholder for computations

R usage and dependencies

• The detector script identifies packages referenced via library(), require(), requireNamespace(), or pkg::function calls and writes them to R.pkgs.
• When R.pkgs exists and evaluation is enabled, CI installs those packages before rendering. Keep the list clean by removing unused library() calls.
• Prefer explicit pkg::function usage in prose chunks so dependencies remain discoverable.

Data, media, and references

• Use relative paths (figures/map.png) to ensure assets render on GitHub Pages.
• Store large data files externally and provide download instructions plus licensing information. Include DOIs or persistent URLs for reproducibility.
• When embedding images, add alt text either via HTML or chunk options to support accessibility.
• Cite external resources using standard Markdown footnotes, Pandoc citation keys, or explicit reference lists. Maintain a references.bib file if you cite bibliographic entries extensively.

Rendering locally

Run the following commands from the repository root during development:

# Optional: refresh dependency list
bash ./scripts/detect_r_packages.sh TG.qmd

# Render the guideline to HTML
quarto render TG.qmd --to html

# Update metadata_qmd.yaml for the directory
bash ./scripts/export_frontmatter.sh TG.qmd

Inspect the generated index.html in a browser before committing.

Common patterns

Load packages with suppressed messages:

library(sf)
library(dplyr)

Enable a single chunk to evaluate when global evaluation is disabled:

result <- 1 + 1
result

[1] 2

Include an image with alt text (relative path):

Checklist before publishing

• YAML metadata is complete (subtitle, authors, abstract, keywords, categories, version, DOI, licence).
• metadata_qmd.yaml regenerated after the final metadata edits.
• If code runs, execute.eval is set appropriately and R.pkgs lists all required packages.
• Figures, tables, and appendices have clear captions and are referenced in the text.
• All external datasets and tools are cited with stable identifiers.
• quarto render TG.qmd --to html succeeds locally without warnings you intend to keep.
• Changes merged into main and the GitHub Pages build finished successfully (check the workflow run and the live site).

Support

Questions or suggestions: tsu.data@ipbes.net