style-guides.qmd

# Style Guides {.unnumbered}

# 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_](https://the-turing-way.netlify.app/community-handbook/style.html#) we follow the [GOV.UK guidance](https://www.gov.uk/guidance/content-design/writing-for-gov-uk) 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.

 ```markdown
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.

 ```markdown
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.

```markdown
> 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](https://quarto.org/docs/authoring/callouts.html) 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](https://www.gov.uk/guidance/style-guide/a-to-z-of-gov-uk-style) 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.

## External links

Write external links using "http://" instead of "www". This ensures they are correctly recognised as hyperlinks.

## 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 back ticks you can add the language name immediately after it (<code>\`\`\`</code> becomes <code>\`\`\`R</code>).

Markdown source:

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

HTML output:

```R
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](https://tools.nhsrcommunity.com/open-code.html#licenceslicenses) 

## Language

Following the [GDS Way](https://gds-way.cloudapps.digital/manuals/licensing.html#language) the NHS-R Community Way will:

>When using a proper name, use the appropriate spelling for that thing (for example 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](https://opensource.org/license/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](https://creativecommons.org/publicdomain/zero/1.0/) 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.

## Copyright

Copyright is held by a person or a legal entity and it should be noted that NHS-R Community is not a legal entity.
NHS-R Community is currently hosted by The Strategy Unit which is part of NHS Midlands and Lancashire, however, most contributors to NHS-R Community work do so under their own organisation's time or even their own time and so will copyright would be to their employer or themselves.

Discussions are ongoing to the use of Crown Copyright (with corresponding licences of [OGL](https://en.wikipedia.org/wiki/Open_Government_Licence)), however, this may require regular submissions of the work with this copyright.

## {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)](https://r4ds.hadley.nz/workflow-style) and the [tidyverse style guide](https://style.tidyverse.org/index.html?q=styler#welcome).

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

## Package and function formatting

As packages and functions in R sometimes use real words and can be confused in text, NHS-R Community refers to packages within curly brackets, for example, {tidyverse}, {ggplot2}, {janitor}.
Functions are formatted with back ticks to change the rendered format and include the rounded brackets, for example, `summarise()` and `filter()`.

The case will also match the original package and function.

# Branding

## Logo

The logo incorporates the [R logo](https://commons.wikimedia.org/wiki/File:R_logo.svg) available under the Creative Commons Attribution-Share Alike 4.0 International licence and is available in png and svg formats through the [assets repository](https://github.com/nhs-r-community/assets/tree/main/logo).

The NHS-R logo has been in use since 2018.

## Colour

The NHS-R logo uses hex colours:

NHS-R Blues #215FAB, #2965AE  
NHS-R Greys #9B9CA3, #B3B4B6  

These colours do not appear in the [NHS brand colours](https://www.england.nhs.uk/nhsidentity/identity-guidelines/colours/) or [NHS Digital Service manual](https://service-manual.nhs.uk/design-system/styles/colour) (includes Sass variables).

Colours for NHS-R Community outputs like the website, slides and themes are based on the NHS brand colours listed and used on the OGL v3.0 licence.

### Themes

- R package [{NHSRtheme}](https://github.com/nhs-r-community/NHSRtheme) with NHS colour themes
- [Quarto report NHS theme](https://github.com/nhs-r-community/quarto-report-nhs-theme)
- [Quarto NHS theme](https://github.com/nhs-r-community/quarto-nhs-theme)

The [assets GitHub repository](https://github.com/nhs-r-community/assets) holds the NHS-R Community logo and `_brand.yml ` which can be used for Quarto products and Shiny.
More information can be found on the [brand.yml](https://posit-dev.github.io/brand-yml/) page.

## Typography

Where possible all other guidance from the [NHS Service Manual](https://service-manual.nhs.uk/design-system/styles/typography) is followed.

NHS-R Community does use the NHS Frutiger font as this is not an official website and would require additional code to be used which not every contributor would have access to.
Code is available in the `_brand.yml` but is commented out and so will not run.

Arial is used in all outputs following NHS guidance of using Arial where Frutiger is not available.

# READMEs in repositories

As standard all NHS-R GitHub repository READMEs should include the following text: 

```
# Installation 

You can install the current version of {name of package} from GitHub with:
```
```{r}
#| eval: false
#| echo: fenced

# install.packages("remotes")
remotes::install_github("nhs-r-community/name-of-package")

```

```
## 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`.