23  Chapter Checklist

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. A more detailed guideline page can be found in Chapter Writing Guidelines.

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.

23.1 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

23.2 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

23.3 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 for emphasis with single underscores
  • If bold is absolutely required, use 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
• 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>

23.4 Callouts

• Quarto callouts 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), see the template or writing guidelines for examples

23.5 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

23.6 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 for examples)
• Code generated tables should also have a label and caption defined in the code block using Quarto syntax (see writing guidelines for examples)
• Labels should be in form of: tbl-<chapternamenopunctiation>-<descriptiveid>

23.7 Figures

• All figure should have a caption and a label (writing guidelines 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

23.8 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 with very large/long-running output should be set to eval=FALSE in the code block options
• Output from large/long-running output should be placed in a collapsible call-out block (writing guidelines 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!’