Language

Language is concerned with the way concepts and ideas in The Turing Way are expressed. A consistent language ensures that The Turing Way is clear and understandable.

Hard Requirements

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

Check 1: Ensure correct grammar and a consistent tone across the book

Correct grammar and consistent tone would help readers of all backgrounds, knowledge, and skill levels to better understand The Turing Way’s content.

Aside from being distracting, incorrect grammar might take away what a piece of text is trying to communicate.

Tools such as Grammarly, Ginger Grammar, and Reverso Speller can help catch grammatical errors present in a piece of text. These tools can be used to assess grammar in new contributions and existing content of The Turing Way. Furthermore, when raising PRs for new content, invite reviewers to check for grammar as well. This could help minimize the number of grammatical errors that make it to the final version of The Turing Way.

With respect to tone, ensure that chapters adhere to a formal style of writing and that sentences are easy to digest. One rule of thumb to consider is that if a sentence needs to be read more than once to be understood, then it likely needs to be rephrased.

Demo

Check 2: Ensure chapters use a consistent language

Note

Language, in this context, refers to the American and British variants of the English language.

With contributors from around the world, The Turing Way does not restrict the language used to write chapters. This makes it easier for contributors to bring in their perspectives as they write content for The Turing Way. Rather, the recommendation is that if a chapter is written in one style (for example, British English), then it should remain consistent throughout. This makes The Turing Way less distracting and easier to read.

Check 3: Ensure Latin abbreviations are not used in writing chapters

When writing content for The Turing Way, the use of Latin abbreviations is discouraged. This is because screen readers may read them aloud in a manner that is confusing to those who rely on such devices.

Furthermore, as described in the style guide, contributions that contain Latin abbreviations will fail the The Turing Way repository’s continuous integration workflow.

Please refer to the style guide for recommendations on how to avoid common Latin abbreviations in your writing.