(ch-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 {ref}`ch-style` 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. (ch-consistency-requirements)= ## 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 {ref}`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](https://github.com/the-turing-way/the-turing-way/issues/1174). ``` ```{figure} ../figures/theturingway-consistency.* --- height: 400px name: theturingway-consistency alt: 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](https://doi.org/10.5281/zenodo.3332807). ``` (ch-consistency-requirements-checklist)= ### Consistency Checklist #### Formatting REQUIREMENT | CHECK | EXAMPLE ----------- | ----- | ------- Hard | Use Markdown for creating your content (see this [WordPress cheatsheet](https://wordpress.com/support/markdown-quick-reference/)). 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 {ref}`style guide` | Hard | Use `MyST` for image formatting as described in the {ref}`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](https://github.com/the-turing-way/the-turing-way/tree/main/book/templates/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 {ref}`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 {ref}`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 {ref}`Formatting`, {ref}`Structure`, and {ref}`Language` subchapters.