The-turing-way: Create consistencies across different chapters

[malvikasharan]

Summary

• Our chapters look very different in a way they have been structures (As we have different authors). In this issue we list a few standards that we want to maintain throughout the chapters

What needs to be done?

• [ ] Remove Table of content (TOC) from the landing page of each chapter: In netlify book, we have access to the content on the right side of the page, and there is quick access to different subchapters in the left side, so we don't need them anymore
• [ ] Create a good summary of each subchapter in the landing page (once the TOCs are removed, this summary will be helpful in navigating subchapters)
• [ ] Split chapters to smaller subchapters to provide modularity
• [ ] Create the reference section with full citation using the Wikipedia referencing format explained here:
  
  
  
  • Examples
  
  
  • Peer-reviewed literature: Aries, Myriam B. C. & Newsham, Guy R. (2008). "Effect of daylight saving time on lighting energy use: a literature review". Energy Policy. 36 (6): 1858–1866. doi:10.1016/j.enpol.2007.05.021. Retrieved October 18, 2013.
  
  
  • Arxiv: Sparling, George A. J. (2006). "Spacetime is spinorial; new dimensions are timelike". arXiv:gr-qc/0610068
  
  
  • Book: Cordell, Bruce R.; Grubb, Jeff; Noonan, David (September 2001). Manual of the Planes (3rd ed.). ISBN 0-7869-1850-0.
  
  
  • A chapter from a book: Bloggs, Fred (January 1, 2001). "Chapter 2: The History of the Bloggs Family". In Doe, John (ed.). Big Compilation Book with Many Chapters and Distinct Chapter Authors. Book Publishers. pp. 100–110. ISBN 978-1-234-56789-7.
  
  
  • Web content: Doe, John (April 30, 2005). "My Favorite Things, Part II". Encyclopedia of Things. Open Publishing. Retrieved May 25, 2020.
  
  

Who can help?

• This issue is created for the new contributors
• Each contributor is encouraged to only format 1-2 chapters only, they can also only partially format the chapters

How to do it?

• Please create a new issue for the chapter you wish to edit and link to this issue by mentioning #1174
  

  - Copy-paste the following checklist to your issue under "### What needs to be done?" to mark what you are working on

Partially fixes #1174

• Chapter name: [ADD NAME HERE]
• [ ] Remove Table of content (TOC) from the landing page of each chapter: In netlify book, we have access to the content on the right side of the page, and there is quick access to different subchapters in the left side, so we don't need them anymore
• [ ] Create a good summary of each subchapter in the landing page (once the TOCs are removed, this summary will be helpful in navigating subchapters)
• [ ] Split chapters to smaller subchapters to provide modularity

- [ ] Create the reference section with full citation using the Wikipedia referencing format explained here

Updates

*

[malvikasharan]

I really like that you are collecting examples. 🎊

Aspects that we are thinking about:

• [ ] Chapter titles
  
  
  
  • [ ] Hard requirement: standard book formatting issues - capitalization etc.
  
  
  • [ ] Soft requirement: TOC titles are preferred to be smaller, and chapter titles can be longer. Think about how we can make the title in the chapter and in TOC consistent: maybe use a shorter title followed by a one-line description
  
  
• [ ] misleading empty files - should not be added to the toc.yml
• [ ] landing pages: summary should capture what rest of the subchapter will talk about (see the chapters in community handbook)
• [ ] remove TOC in chapters (we already have them in the left and right)
• [ ] Consistency with style guide - referencing, linking
• [ ] Bibliography - explain where it lands and not to create chapter wise bibliography
• [ ] Image: Referencing should be updated from MarkDown to Sphinx
  
  
  
  • [ ] size should be smaller: decide on the maximum size
  
  

Additional things to discuss:

• [ ] Hard requirement vs soft requirement
• [ ] language - we don't force people to use a specific English type - but for example, if a chapter is written in American/British English, it should consistently follow-through - this is retrospective, of course, so maybe a second reviewer can be requested after a subchapter has been reviewed and is ready to merge.

For the future:

• [ ] Updating chapter template to capture what we do now
• [ ] Remove some of the sections we don't want to use
• [ ] Choose some chapters as blue-prints

[paulowoicho]

Here are some of the thoughts I have about this:

1. While working on the Guide for Reproducible Research, I noticed that the other guides did not have an Overview chapter. I was wondering if it would be worth adding an Overview chapter for all the other guides.

2. I noticed that chapter landing pages generally follow this format (like the Licensing chapter in the Guide for Reproducible Research):
   1. Chapter Title
   - _Prerequisites/Recommended Skill Level_
   - _Summary_
   - _Why this is useful_
   For the chapters that do not follow this format, I think we can work on adding in the missing sections.

[paulowoicho]

Updated Consistency Checklist

• Remove ToCs from Chapter body since one is auto-generated by jupyter-books
• Ensure each subchapter has a good summary in their landing page
• Split long chapters to smaller chapters, so they are modular.
• Create a references/bibliography section using Wikipedia’s referencing format
• Ensure the names of chapters/subchapters map exactly to the left TOC.
• Ensure consistency with the Turing Way Style Guide
• Ensure correct grammar and a consistent tone across the book (I am also using Grammarly to help with this)
• Make images, chapters, subchapters, and sections of the book 'reference-able' by adding labels.
• Convert all HTML formatting to markdown
• Ensure proper title casing for headers
• Make images responsive so that its size adapts to the screen size of the device the book is read from (Updating from Markdown to Sphinx)
• Remove misleading empty files from the TOC
• Ensure consistent language in chapters (if American English stay consistent; if British stay consistent etc)
• Ensure chapters follow the structure shown in the attached image:

Things to think about:

• Updating the chapter templates to capture what we do now
• Removing some of the sections we don't want to use
• Choosing some chapters as blue-prints

[malvikasharan]

@paulowoicho Can you please review this comment and add the missing bit in your checklist?
https://github.com/alan-turing-institute/the-turing-way/issues/1174#issuecomment-643204556

[malvikasharan]

@paulowoicho a couple of things we don't have in the consistency chapters yet that should be considered in the PR #1459

• Requirement section on the top of the file: What skills are needed for this chapter (link to different chapters that readers should know)
• Bibliography and citing external resources (part of hard requirement)

[paulowoicho]

@paulowoicho a couple of things we don't have in the consistency chapters yet that should be considered in the PR #1459

• Requirement section on the top of the file: What skills are needed for this chapter (link to different chapters that a reader should know)
• Bibligraphy and citing external resources (part of hard requirement)

Thanks for the thorough review!

I will add a section for this in my next commit!

[malvikasharan]

I haven't yet reviewed the subchapters, but let do it one by one. 💪