Maintaining Consistency#

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.

Important

Please note that these requirements are not exhaustive or definitive, and neither are their classifications rigid. Moreover, no items are inherently more important than the other.

If you identify more consistency issues that need to be addressed, join the conversation here.

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.

Pathway to maintaining consistency. The Turing Way project illustration by Scriberia. Used under a CC-BY 4.0 licence. DOI: 10.5281/zenodo.3332807.#

Consistency Checklist#

Formatting#

REQUIREMENT

CHECK

EXAMPLE

Hard

Use Markdown for creating your content (see this WordPress cheatsheet).

Hard

Use the headers in sequential order. For example, starting the top level with h1 tag #, second-level header with h2 tag ## and so on.

Hard

Add labels to chapters, subchapters and images to enable cross-referencing as described in the style guide

Hard

Use MyST for image formatting as described in the style guide

Use public domain images that are less than 1MB in size and cite appropriately.

Hard

If you are using a colon (:) in the title of your chapter/subchapter, ensure that the whole title is escaped with quotation marks (") in the _toc.yml file. Not doing so will cause the book build to fail due to YAML errors.

- title: "Case Studies: Choosing an ML License"

Soft

Ensure that the names of chapters/subchapters are short and map exactly to how they are titled in the _toc.yml

Soft

Ensure proper title-casing for headers

Capitalise the first, last and ‘important’ words of every title; for example, ‘Snow White and the Seven Dwarves’.

Structure#

REQUIREMENT

CHECK

Hard

Ensure chapters follow a structure as described in the new chapter template

Hard

Do not add a ‘table of contents’ in chapters or subchapters as it is auto-generated by the Jupyter Book

Hard

Ensure external sources are properly referenced and included in the centralised BibTeX file as recommended in the style guide

Hard

Do not add any empty files in the _toc.yml, instead create an issue for new chapters

Soft

Ensure each chapter has a good summary on its landing page along with links to its subchapters.

Soft

Split long chapters into smaller subchapters so they are modular.

Language#

REQUIREMENT

CHECK

Hard

Ensure chapters do not use any Latin abbreviation as discussed in the style guide

Hard

Ensure correct grammar and a consistent tone across the book with the help of 1-2 reviewers

Hard

Ensure 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.