(ch-consistency-structure)= # Structure Structure refers to how _The Turing Way_ is organised. A good structural framework ensures that _The Turing Way's_ content is presented in an orderly manner. (ch-consistency-structure-hr)= ## Hard Requirements The hard checks that deal with _The Turing Way's_ structure include: (ch-consistency-structure-hr-emptyfiles)= ### Check 1: Do not add empty files in the `_toc.yml` The `_toc.yml` file is where _The Turing Way's_ table of contents (ToC) lives. Some files referenced in the ToC are empty, and their inclusion means that readers can navigate to an empty (sub)chapter while reading _The Turing Way_. This negatively impacts the reader's experience as they go through the book. ```{figure} ../../figures/empty-toc-file.* --- name: empty-toc-file alt: An empty file that was included in the Turing Way's Table of Contents. Readers can still navigate to empty files when they are included in the table of contents. --- Empty files included in _The Turing Way's_ Table of Contents can still be accessed by readers. ``` A general suggestion is to remove references to such files from the ToC and raise an issue in _The Turing Way_ Github [repo](https://github.com/the-turing-way/the-turing-way) for content to be written for those files. When the content is written, the files can then be added to the ToC. For example, [this issue](https://github.com/the-turing-way/the-turing-way/issues/1391) curates a list of empty and incomplete files currently in _The Turing Way_, and [this PR](https://github.com/the-turing-way/the-turing-way/pull/1448) writes content for the `Data Licences` subchapter shown in the {ref}`image `. (ch-consistency-structure-hr-structure)= ### Check 2: Ensure chapters follow a consistent structure _The Turing Way_ is made up of five guides that contain several chapters and subchapters. However, these chapters do not follow a uniform structure, taking away from the reader's experience. ```{figure} ../../figures/recommended-chapter-structure.* --- name: recommended-chapter-structure alt: The recommended structure for chapters in The Turing Way. Chapters should have a landing page with a sections for prerequisites, summary, and why the chapter is useful. Chapters should also have a checklist and a resources subchapter in addition to the rest of the chapter content. --- Recommended structure for chapters in The Turing Way. ``` - **Landing page:** - The chapter's landing page should include information about any prerequisites required to understand the chapter, a summary of the chapter's content, and an explanation of why the chapter is useful. - **Subchapters:** - A chapter can contain any number of subchapters or none at all. However, please note the next requirement about the checklist and resources subchapters. - **Checklist subchapter:** - The checklist subchapter itemizes action points for the reader to take based on the concepts introduced in the chapter. - **Resources subchapter:** - The resources subchapter points the reader to other sources where they can learn more about the concepts discussed in the chapter, as well as related topics to explore. ```{attention} Please note that making chapters follow this structure may require splitting some of the existing content into new files. References to these files should be updated in the table of contents in the `_toc.yml` file. ``` Refer to the [chapter template](https://github.com/the-turing-way/the-turing-way/tree/main/book/templates/chapter-template) to structure new chapter contributions, and use it to assess current chapters in _The Turing Way_. For chapters that do not fit this structure, please raise a Pull Request. (ch-consistency-structure-hr-toc)= ### Check 3: Do not add a 'table of content' in chapters or subchapters. Some chapters in _The Turing Way_ were written with a hand-crafted table of contents. However, Jupyter Book auto-generates a permanent table of contents that can be found on the left side of _The Turing Way_ book, and a dynamic, page-specific table of content located at the top-right of each page. This makes a manually written table of contents unnecessary, and it may negatively impact a reader's experience with _The Turing Way_. ```{figure} ../../figures/many-table-of-contents.* --- name: many-table-of-contents alt: A subchapter in The Turing Way with three table of contents. Two that are generated by Jupyter Book and one made by the chapter author. --- The manually written table of contents is unnecessary as Jupyter Book auto-generates two separate table of contents. ``` #### Demo
(ch-consistency-structure-hr-citing)= ### Ensure external sources are properly cited and referenced As described in the {ref}`style guide`, _The Turing Way_'s book-wide references are stored in a BibTeX file called `references.bib`. When writing new content, ensure that information culled from external sources are cited using the BibTeX format and added to the `references.bib` file as appropriate. The {ref}`style guide` demonstrates how to add a new reference to the centralised BibTeX file, and shows how this reference can be included in your writing. (ch-consistency-structure-soft-req)= ## Soft Requirements Soft requirements that deal with _The Turing Way's_ structure include: (ch-consistency-structure-sr-summary)= ### Check 1: Ensure each chapter has a good summary in its landing page A chapter with a good summary gives the reader an overview of the content that follows. Ideally, summaries should communicate the main idea of the chapter and identify any supporting detail, but be brief and precise. Summaries should also adequately cross-reference the chapter's subchapters, for the benefit of readers who may want to quickly explore the topics the summary introduces. Chapters in _The Turing Way_ that contain summaries that do not fit these criteria may need to be reworded or rewritten. (ch-consistency-structure-sr-modular)= ### Check 2: Split long chapters into smaller subchapters so they are modular Long chapters may be difficult for some readers to go through. Furthermore, very long content can be intimidating for other readers who may only be interested in the main ideas the chapter talks about. Therefore, to make _The Turing Way_ easier to read, long chapters should be appropriately modularised. When keeping chapters modular, ensure that its subchapters only talk about one aspect of the overall topic. For example, if a chapter on Machine Learning was to be written for _The Turing Way_, such a chapter should contain at least three subchapters that each focus on Supervised Learning, Unsupervised Learning, and Reinforcement Learning.