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.

Hard Requirements#

The hard checks that deal with The Turing Way’s structure include:

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.

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.

Fig. 169 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 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 curates a list of empty and incomplete files currently in The Turing Way, and this PR writes content for the Data Licences subchapter shown in the image.

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.

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

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.

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.

Fig. 171 The manually written table of contents is unnecessary as Jupyter Book auto-generates two separate table of contents.#

Demo#

Ensure external sources are properly cited and referenced#

As described in the 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 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.

Soft Requirements#

Soft requirements that deal with The Turing Way’s structure include:

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.

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.