Skip to article frontmatterSkip to article content

The Turing Way is an open-source project that empowers contributors around the world to leverage their skills, knowledge, and expertise to build and expand its content. The Turing Way guides are continually evolving, with multiple chapters co-developed by individuals from varied backgrounds - who are all passionate about sharing knowledge around data science and research. To sustain and support this vibrant community, The Turing Way book should remain consistent and accessible as it evolves. The Style Guide chapter already provides guidelines for maintaining a consistent style across the book. However, not all chapters follow these suggestions since they’re often written asynchronously by different authors. Reviewing consistency across The Turing Way alone is reasonably challenging. This points towards a need to encourage and support our contributors to maintain consistency throughout the chapters in The Turing Way guides. Therefore, this chapter will outline a step-by-step consistency checklist that will guide our contributors. Each step will emphasize a consistency check to look out for as they design and develop chapters in The Turing Way or bring consistency to existing chapters.

Hard vs Soft Requirements

Items in the consistency checklist are categorised into hard and soft requirements. Hard requirements are essential consistency checks that a chapter must pass so that The Turing Way builds without errors. Moreover, they make the chapter readable and accessible to everyone.

Soft requirements, on the other hand, are nice-to-have consistency checks that a chapter should pass. These checks greatly enhance the overall look and feel of the book, but can be safely ignored if they cannot be integrated into your contribution. You can always return to review your past contributions and enhance their content.

An overview of these requirements is itemised below. For easy description, these consistency checks are classified by format, structure, and language. The subchapters explain these in more detail and describe how they can be achieved.

This illustration shows a staircase indicating pathway to maintain consistency that has three pillars - formatting, structure and language. One person is guiding two new contributors up the staires.

Figure 1:Pathway to maintaining consistency. The Turing Way project illustration by Scriberia. Used under a CC-BY 4.0 licence. DOI: The Turing Way Community & Scriberia (2024).

Consistency Checklist

Formatting

REQUIREMENTCHECKEXAMPLE
HardUse Markdown for creating your content (see this WordPress cheatsheet).
HardUse the headers in sequential order. For example, starting the top level with h1 tag #, second-level header with h2 tag ## and so on.
HardAdd labels to chapters, subchapters and images to enable cross-referencing as described in the style guide
HardUse MyST for image formatting as described in the style guideUse public domain images that are less than 1MB in size and cite appropriately.
HardIf you are using a colon (:) in the title of your chapter/subchapter, ensure that the whole title is escaped with quotation marks (") in the myst.yml file. Not doing so will cause the book build to fail due to YAML errors.- title: "Case Studies: Choosing an ML License"
SoftEnsure that the names of chapters/subchapters are short and map exactly to how they are titled in the myst.yml
SoftEnsure proper title-casing for headersCapitalise the first, last and ‘important’ words of every title; for example, ‘Snow White and the Seven Dwarves’.

Structure

REQUIREMENTCHECK
HardEnsure chapters follow a structure as described in the new chapter template
HardDo not add a ‘table of contents’ in chapters or subchapters as it is auto-generated by the Jupyter Book
HardEnsure external sources are properly referenced and included in the centralised BibTeX file as recommended in the style guide
HardDo not add any empty files in the myst.yml, instead create an issue for new chapters
SoftEnsure each chapter has a good summary on its landing page along with links to its subchapters.
SoftSplit long chapters into smaller subchapters so they are modular.

Language

REQUIREMENTCHECK
HardEnsure chapters do not use any Latin abbreviation as discussed in the style guide
HardEnsure correct grammar and a consistent tone across the book with the help of 1-2 reviewers
HardEnsure chapters use a consistent language, for example, if you choose to write in British English, maintain that throughout

These checks are further explained in the Formatting, Structure, and Language subchapters.

References
  1. The Turing Way Community, & Scriberia. (2024). Illustrations from The Turing Way: Shared under CC-BY 4.0 for reuse. Zenodo. 10.5281/ZENODO.3332807