chapter-checklist.qmd

---
title: Chapter Checklist
author: James A. Fellows Yates
---

This page acts as a quick-reference checklist when going through the chapter writing process to ensure consistency between chapters.
A template to start writing a new chapter can be found in [Chapter Template](chapter-template.qmd).
A more detailed guideline page can be found in [Chapter Writing Guidelines](chapter-writing-guidelines.qmd).

We generally recommend you go through your chapter repeatedly, each time going through one of the checklist sections below. 
This will help make the editing process more manageable by only considering one type of object each time.

## Structure

- Each chapter should start with a brief introduction (without header!) and bullet point list of learning objectives
- Each chapter's penultimate header should be `# Summary` and summarise list of key takeaway messages
- Each chapter that has used citations should have the last section as `# References` with nothing under underneath
- Headers should either be two- or three-levels deep (e.g. `##` or `###`), and no deeper or fewer.
    - The single level header is reserved for the chapter title
- Data should not be stored in the textbook, but rather linked to Zenodo archives (generally set up by the summer school organising team)
- Each major section should end in a mini-test question/answer block in a specially formatted [call-out](#callouts)

## Language

- All text should be in British english
- Please always use a spelling check tool
- Collective first person 'we'/'us'/'our' should be used (i.e., generally remove 'I'/'my' or 'you'/'your' etc. where possible)
    - Exceptions can be the learning objectivesm question/answer blocks, and summary sections

## Text Formatting

- Each sentence should be on a new line
- Each paragraph should be separated from the previous paragraph with an empty line
- Bullet points lists 
    - Should be indicated with a `-` and sub-points with a 4-space indent
    - Bullet points should start with a capital letter and end with no full stop
- Emphasis
    - Use _italics_ (`_italics_`) for emphasis with single underscores (`_italics_`)
    - If bold can be used for potential 'glossary words', or as to highlight first word of bullet point lists, and can be formatted with **double asterisks** (`**double asterisks**`)
- External URLs should be in the format `[SPAAM Website](https://spaam-community.org)`
- Internal links to other pages or sections are recommended where possible, and should be in the format `[Chapter Checklist](chapter-checklist.qmd)` for other pages or `[Text Formatting](#text-formatting)` for internal-sections
- Do not use quote blocks for text that is not a direct quote (i.e., don't use the Markdown `>` syntax)
    - Instead use [callouts](#callouts)
- Paths should generally be relative to the working directory of the chapter's practical session
- Place holder text (e.g. in paths etc.) should be lower case and in angled brackets, for example `<path>/<to>/<something>`

## Callouts

- [Quarto callouts](https://quarto.org/docs/authoring/callouts.html) should be used for any text that requires special attention from the reader, for example warnings, tips, etc. 
- A special format of call-out is used for the end-of-section mini-test questions and answers ([see](#structure)), see the [template](chapter-template.qmd) or [writing guidelines](chapter-writing-guidelines.qmd) for examples

## References

- All chapters that use citations must have a dedicated `.bib` file under `assets/references/` and should be defined in the markdown header
- In text citations are made like this @Fellows-Yates2024-tg or [@Fellows-Yates2024-tg]
    - You don't need to write brackets yourself, the square brackets will be rendered accordingly
- Bibliographies don't need to be written manually, they will automatically be rendered for you at the end of the chapter

## Tables

- Tables should be ideally formatted using markdown syntax
- All tables should be referenced in the text
- All tables should have a caption and label ([writing guidelines](chapter-writing-guidelines.qmd) for examples)
- Code generated tables should also have a label and caption defined in the code block using Quarto syntax (see [writing guidelines](chapter-writing-guidelines.qmd) for examples)
- Labels should be in form of: `tbl-<chapternamenopunctiation>-<descriptiveid>`

## Figures

- All figure should have a caption and a label ([writing guidelines](chapter-writing-guidelines.qmd) for examples)
- Labels should be in form of: `fig-<chapternamenopunctiation>-<descriptiveid>`
- All figures should be referenced in text
- Captions should be descriptive to aid accessibility

## Code Blocks

- Text prior code blocks should end in a full stop
- Inline code defined with single `backticks` should be used for a single word or object (e.g., `variable`, `tool`, `.suffix`)
- All commands or longer code related text must go in a dedicated markdown triple backticks with the language specified (e.g., ````bash`)
- Do not prefix commands with a `$` or `>` to indicate a command prompt
- Code blocks that automatically execute in Quarto (e.g. R), output should be set to `eval=FALSE` in the code block options, unless the code/plot is expected to executed on the fly
- Output from large/long-running output should be placed in a collapsible call-out block ([writing guidelines](chapter-writing-guidelines.qmd) for examples)
- Code for self-guided chapter set-up should be wrapped in a collapsible note call-out block with a 'Self guided: \<title\>' format
- Example code that should not be run by the user should wrapped in a 'warning' call-out block with the title 'Example command - do not run!'