Style Guide¶
To ensure that the book can be read easily by everyone, including screen readers and non-native english speakers, we have compiled a set of guideline to keep a consistent style across all chapters of the book.
We follow the Gov.uk guidance to improve accessibility of the resources in The Turing Way.
Write each sentences in a new line (line breaks)¶
Please write all sentence in the markdown file on separate lines. Having each sentence on a new line will make no difference to how the text is displayed, there will still be paragraphs, but it will mean that any pull requests will be easier to check; the changes will be on a single line instead of somewhere in a paragraph. Consider the example below.
Today you are you, that is truer than true. There is no one alive who is youer than you. - Dr Seuss
A pull request on this correcting it to have a ‘.’ after Dr would show as a change to the whole paragraph. Contrast this with the next example which will be displayed online in the exact same way, but would see a change to a single line.
Today you are you, that is truer than true.
There is no one alive who is youer than you.
- Dr Seuss
Opinions are welcome, but …¶
The Turing Way book is intended to be only lightly opinionated.
Whilst more opinionated content is allowed, such content should be clearly marked.
The best way to do this is by displaying it in a quote box.
This can be done by either prefixing every line with the greater than symbol >.
Note, that the formatting will be retained, so we can split each sentence to a new line as recommended before.
> I will not eat them in a house,
> i will not eat them with a mouse,
> i will not eat them in a box i will not eat them with a fox,
> i will not eat them here of there i will not eat them anywhere,
> I do not like green eggs and ham i do not like them sam i am
Avoid Latin Abbreviation¶
Please do not use Latin abbreviations. See the Gov.uk recommendations for details.
Some of these abbreviations are:
Fig. 14 A list of latin abbreviations for exempli gratia (for example), et-cetera (so on), and id est (that is). Screenshot of part of the list of Common Latin Abbreviations for APA Style.¶
Instead of the first abbreviation in the table for exempli gratia, which can sometimes read aloud as ‘egg’ by screen reading software, please use ‘for example’ or ‘such as’ or ‘like’ or ‘including’ - whichever works best in the specific context.
Instead of the second abbreviation in the table for et-cetera to indicate open ended list, please start the list with words like ‘for example’ or ‘such as’ or ‘like’ or ‘including’.
Instead of third abbreviation in the table for id est that is often used to clarify a sentence, try (re)writing sentences to avoid the need to use it. If that is not possible, use an alternative such as ‘meaning’ or ‘that is’.
Any chapter containing a Latin abbreviation will fail the continuos integration (CI) workflow of the The Turing Way GitHub repository from passing successfully, which is tested by this Python script.
To avoid CI from failing, even in this chapter we have avoided to write those abbreviations and instead used an image to illustrate the above examples.