Style Guides

Style Guide for text

To ensure that text like books, websites and blogs can be read easily by everyone, including screen readers and non-native English speakers, we have compiled a set of guidelines to keep a consistent style.

As recommended in the The Turing Way we follow the GOV.UK guidance to improve accessibility.

Write each sentence in a new line (line breaks)

Please write all sentences 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 NHS-R Community 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

Quarto also allows for call out boxes for further and specific emphasis including notes, warnings, important, tips and caution.

Avoid Latin Abbreviation

Please do not use Latin abbreviations. See the Gov.uk recommendations for details.

Some of these abbreviations are:

  • exempli gratia (for example)
  • et-cetera (so on) and
  • id est (that is)

These examples are not written out in their shortened form as the book can be set to fail to publish with Latin abbreviations through GitHub to enforce this 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’.

Explain acronyms

The NHS and many other public sector organisations often rely on acronyms to shorten long texts and names like

NHS Midland and Lancashire Commissioning Support Unit

becomes MLCSU.

Not everyone will be familiar with these acronyms, even if they work in the same sector like healthcare. It’s fair to continue to use NHS as we rarely say National Health Service but do consider your audience as not everyone is familiar with the NHS and what it does (and doesn’t do).

For technical language, also consider explaining the acronym, at least once at the beginning of the text. This can be in the form:

Continuous Integration (CI)

so that whenever CI is referenced later its full form is in the text.

Use capitals wisely

Screen readers will read capitals as if they are acronyms which works for things like NHS and MLCSU. Because a screen reader read each letter, using capitals for emphasis in text like:

DO NOT do this

could result in a screen reader spelling out the words do and not by individual letters. It’s also felt to be a bit like shouting in text so consider other ways of emphasis.

Chunks with code or special text

You can ensure that any code (or Markdown) chunks you have in the guide have the code syntax highlighted by mentioning the language in question. As an example, if you want to have some R code, when you open the chunk with three backticks you can add the language name immediately after it (``` becomes ```R).

Markdown source:

    ```R
    x <- c(1:21)
    ```

HTML output:

x <- c(1:21)

Referencing R packages and functions in text

Because a number of popular R packages use common names like janitor it can help distinguish the word refers to a package by using curly brackets: {janitor}.

To highlight the use of a package in text using markdown formatting put function names in back ticks: mutate() along with rounded brackets.

Style Guide for code

Licences/licenses

Further information on the types of licences and how to get the text required for projects can be found on the Statement on Tools book

Language

Following the GDS Way the NHS-R Community Way will:

When using a proper name, use the appropriate spelling for that thing (e.g. the MIT License.)

and:

Each repository should include a licence file. This should be called LICENCE or LICENCE.md.

Licences to use

NHS-R Community repositories are licenced under MIT for code based projects like Shiny apps and packages:

the MIT License is a permissive software license that places few restrictions of reuse. Users of software using an MIT License are permitted to use, copy, modify, merge publish, distribute, sublicense and sell copies of the software.

Note that any copyright needs to be copied retained in any copies:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

and CC0 for text based projects like training and books (like this):

allows the creator to retain copyright whilst allowing others to copy and distribute and make use of their work non-commercially. The Creative Commons license also ensures creators get the recognition and credit for the work they produce and share.

There are more than one type of Creative Commons licence and represents a spectrum between public domain and all rights reserved https://en.wikipedia.org/wiki/Creative_Commons_license#Types_of_licenses

Creative Commons licences are to be avoided for software (by implication code) due to backward-compatibility limitations and are also irrevocable, so any work taken under the licence can continue to be used under those original terms.

{styler}, {lintr} packages and tidyverse Style Guide

It is highly recommended that code that is produced for and by NHS-R Community has {styler} applied to it as detailed in the R for Data Science (2nd Edition) and the tidyverse style guide.

The use of the package {lintr} is also highly recommended and can show particular style issues that may not be automatically corrected through using {styler}.

READMEs in repositories

As standard all NHS-R GitHub repository READMEs should include the following text that refers to the Code of Conduct in this book:

## Contributing

Please see our 
[guidance on how to contribute](https://tools.nhsrcommunity.com/contribution.html).

This project is released with a Contributor [Code of Conduct](./CODE_OF_CONDUCT.md). 
By contributing to this project, you agree to abide by its terms.

The simplest way to contribute is to raise an issue detailing the feature or 
functionality you would like to see added, or any unexpected behaviour or bugs 
you have experienced.

## Special note of thanks

**Use if required**

To create a code of conduct file use the code from the {usethis} package:

use_code_of_conduct(contact = "nhs.rcommunity@nhs.net")

which generates a file CODE_OF_CONDUCT.md.