Maintaining Consistency

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.

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.