Skip to content

Commit

Permalink
Merge pull request #53 from NHSDigital/release/v1.8.0
Browse files Browse the repository at this point in the history
Release v1.8.0
  • Loading branch information
jenniferstruthers1-nhs committed Mar 1, 2024
2 parents f5d0af1 + 2376f06 commit dba9f7e
Show file tree
Hide file tree
Showing 92 changed files with 1,589 additions and 509 deletions.
6 changes: 5 additions & 1 deletion docs/about.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,13 @@
---
title: RAP Community of Practice

tags:
- RAP CoP website
hide:
- navigation
---

# RAP Community of Practice
#

> **This material is maintained by the [NHS England RAP Community of Practice](mailto:england.rapchampions@nhs.net)**.
Expand Down
234 changes: 121 additions & 113 deletions docs/example_RAP_CoP_page.md
Original file line number Diff line number Diff line change
@@ -1,113 +1,121 @@
# Page Template

## Some introductory subtitle

!!! tip "TLDR"
- **very brief** summary of the main findings
- any key links i.e. to forms or other things people need fill in
- try to keep it to just three

??? question "Why should we care?"
- Brief summary of why this is important
- any key links of background
- We can have a bigger section on this below

??? success "Pre-requisites"
* Some information on what someone might need to be familiar with before they can use this page

|Pre-requisite | Importance | Note |
|--------------|------------|------|
|[Some link to some other guide we have](https://nhsdigital.github.io/rap-community-of-practice/)|Necessary/Helpful|Any comment we have on this|
|some other guide|Helpful|another note|

!!! info inline end
XKCD comics can also be great at grabbing attention:

![An amusing comic about marketing](https://imgs.xkcd.com/comics/immune_system.png "An amusing comic about marketing")

**Don't forget to update the `mkdocs.yml` file to add this page, so it appears in the nav bar!**

Here we need some bit explaining the background of the thing the page is talking about

- keep it brief
- make it clear what it is and what the benefit is
- don't go into details of the methods, but perhaps highlight some of the key approaches described below

## First subtitle of the main content

Talk about the issue break it down into steps.

We might even include a little diagram:

```mermaid
graph LR
A[Have an idea] --> B{Make a page};
B -->|Pull Request| C[Colleagues Review];
C --> D[Feedback];
D --> B;
B ----->|Approved| E[Publish!];
```

Consider linking to other pages and try and extract the general concept from language specific implementations, i.e. we could have a pager about "functions", and then link to specific pages on how to do functions in Python and R.

Also, have a look on the following pages to see if they have guidance we could link to, or adapt
- [Quality Assurance of Code for Analytics](https://best-practice-and-impact.github.io/qa-of-code-guidance/intro.html)
- [Turing Way](https://the-turing-way.netlify.app/welcome.html)
- [Central RAP Guidance from GSS](https://analysisfunction.civilservice.gov.uk/support/reproducible-analytical-pipelines/)

## General subsection template

Write some content here

### General subsubsection template

This might be on some specific aspect of the subsection

#### General subsubsubsection template

We might need to get even more specific, but probably wont use this as much!

## Further subtitles

You can include code snippets `inline` or in blocks:

```Python
print("hello world")
```

You might also want to hide large code snippets:

??? example "Some big code snippet"
```Python
print("HA, I lied, it's only a small code snippet")
```

!!! note
Admonition blocks can be helpful to bring out key points

See [mkdocs guidance]()

## Further subsections

Continue to work through the subject, but we don't have to make the pages long - a short page can be just as useful!

You can include pictures, however referencing them requires a few steps back in the directory tree (see below):

![image-alt-text](images/add_file.PNG "Some random picture")

You can also have tabs:

=== "Tab 1"
We can put whatever we want in here
```Python
def somefunc(a):
return None
```

=== "Tab 2"
And in here something completely different, such as a diagram
![alt text](images/branch_info.JPG "Some random picture")

## Further Reading

- Provide any useful links people might need to further their learning
---
title: Add your title here

# Uncomment and add your tags here
# tags:
# -
---

#

## Some introductory subtitle

!!! tip "TLDR"
- **very brief** summary of the main findings
- any key links i.e. to forms or other things people need fill in
- try to keep it to just three

??? question "Why should we care?"
- Brief summary of why this is important
- any key links of background
- We can have a bigger section on this below

??? success "Pre-requisites"
* Some information on what someone might need to be familiar with before they can use this page

|Pre-requisite | Importance | Note |
|--------------|------------|------|
|[Some link to some other guide we have](https://nhsdigital.github.io/rap-community-of-practice/)|Necessary/Helpful|Any comment we have on this|
|some other guide|Helpful|another note|

!!! info inline end
XKCD comics can also be great at grabbing attention:

![An amusing comic about marketing](https://imgs.xkcd.com/comics/immune_system.png "An amusing comic about marketing")

**Don't forget to update the `mkdocs.yml` file to add this page, so it appears in the nav bar!**

Here we need some bit explaining the background of the thing the page is talking about

- keep it brief
- make it clear what it is and what the benefit is
- don't go into details of the methods, but perhaps highlight some of the key approaches described below

## First subtitle of the main content

Talk about the issue break it down into steps.

We might even include a little diagram:

```mermaid
graph LR
A[Have an idea] --> B{Make a page};
B -->|Pull Request| C[Colleagues Review];
C --> D[Feedback];
D --> B;
B ----->|Approved| E[Publish!];
```

Consider linking to other pages and try and extract the general concept from language specific implementations, i.e. we could have a pager about "functions", and then link to specific pages on how to do functions in Python and R.

Also, have a look on the following pages to see if they have guidance we could link to, or adapt
- [Quality Assurance of Code for Analytics](https://best-practice-and-impact.github.io/qa-of-code-guidance/intro.html)
- [Turing Way](https://the-turing-way.netlify.app/welcome.html)
- [Central RAP Guidance from GSS](https://analysisfunction.civilservice.gov.uk/support/reproducible-analytical-pipelines/)

## General subsection template

Write some content here

### General subsubsection template

This might be on some specific aspect of the subsection

#### General subsubsubsection template

We might need to get even more specific, but probably wont use this as much!

## Further subtitles

You can include code snippets `inline` or in blocks:

```Python
print("hello world")
```

You might also want to hide large code snippets:

??? example "Some big code snippet"
```Python
print("HA, I lied, it's only a small code snippet")
```

!!! note
Admonition blocks can be helpful to bring out key points

See [mkdocs guidance]()

## Further subsections

Continue to work through the subject, but we don't have to make the pages long - a short page can be just as useful!

You can include pictures, however referencing them requires a few steps back in the directory tree (see below):

![image-alt-text](images/add_file.PNG "Some random picture")

You can also have tabs:

=== "Tab 1"
We can put whatever we want in here
```Python
def somefunc(a):
return None
```

=== "Tab 2"
And in here something completely different, such as a diagram
![alt text](images/branch_info.JPG "Some random picture")

## Further Reading

- Provide any useful links people might need to further their learning
39 changes: 22 additions & 17 deletions docs/glossary.md
Original file line number Diff line number Diff line change
@@ -1,25 +1,12 @@
---
title: Glossary
tags:
- Glossary
hide:
- navigation
---

## RAP

RAP stands for Reproducible Analytical Pipelines. The term comes from UK public sector data scientists - you can [read the ONS description here](https://datasciencecampus.ons.gov.uk/capability/data-science-campus-faculty/reproducible-analytical-pipeline-journey/#:~:text=Reproducible%20Analytical%20Pipelines%20are%20programs,impressive%20efficiencies%20in%20your%20teams.). We also have a page on [why RAP is important](introduction_to_RAP/why_RAP_is_important.md)

## Pipeline

A data pipeline is a series of steps or processes that are used to collect, process, and transform data from various sources into a format that can be easily used. The pipeline typically includes data ingestion, data cleaning, and some analysis. A good pipeline can automate work as well as improving the quality of the outcomes.

## Virtual Environments

Virtual environments are a way to ensure that you have maximum control over the code that you're writing and how it will run. Many software packages interact with one another, and not always in a good or predictable way. Virtual environments allow you to develop code like it is being done on a completely clean, separate machine. In a virtual environment, you can install whatever packages you want, at whatever version, without worrying about affecting the other software or projects you might have on your computer.

Best practice recommends that we create a different virtual environment for each project that we work on.

## Venv

`venv` is a particular package for managing virtual environments in Python, which comes pre-installed with python. We highly recommend using this package, although others are available. See [our page](training_resources/python/virtual-environments/venv.md) for advice on using it.
#

## Conda

Expand All @@ -35,3 +22,21 @@ You can read more about git on our [introduction to Git](training_resources/git/

An IDE (Integrated Development Environment) is a piece of software you can use to write code. You can write code anywhere that you can write plain text, but IDEs are designed to help with the process. It doesn't affect how the code will run, and you can move the code safely between IDEs.
IDEs are packed with useful features like autocompletion, test suites, git integration, linting and more. We recommend Visual Studio Code, but you can also try PyCham, Spyder, or Eclipse - to name a few.

## Pipeline

A data pipeline is a series of steps or processes that are used to collect, process, and transform data from various sources into a format that can be easily used. The pipeline typically includes data ingestion, data cleaning, and some analysis. A good pipeline can automate work as well as improving the quality of the outcomes.

## RAP

RAP stands for Reproducible Analytical Pipelines. The term comes from UK public sector data scientists - you can [read the ONS description here](https://datasciencecampus.ons.gov.uk/capability/data-science-campus-faculty/reproducible-analytical-pipeline-journey/#:~:text=Reproducible%20Analytical%20Pipelines%20are%20programs,impressive%20efficiencies%20in%20your%20teams.). We also have a page on [why RAP is important](introduction_to_RAP/why_RAP_is_important.md)

## Venv

`venv` is a particular package for managing virtual environments in Python, which comes pre-installed with python. We highly recommend using this package, although others are available. See [our page](training_resources/python/virtual-environments/venv.md) for advice on using it.

## Virtual Environments

Virtual environments are a way to ensure that you have maximum control over the code that you're writing and how it will run. Many software packages interact with one another, and not always in a good or predictable way. Virtual environments allow you to develop code like it is being done on a completely clean, separate machine. In a virtual environment, you can install whatever packages you want, at whatever version, without worrying about affecting the other software or projects you might have on your computer.

Best practice recommends that we create a different virtual environment for each project that we work on.
Binary file added docs/images/JS_network.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/chi-onwurah-pmq-rap.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/clipart_copy.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/clipart_magglass.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/clipart_map.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/code_review.jpg
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/copy_image.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/flowers.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/magnifying_glass.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/manual_version_control.jpg
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/network.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/the-rap-journey-long-with-text.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/your-country-needs-you-to-rap.jpg
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
9 changes: 8 additions & 1 deletion docs/implementing_RAP/accessibility-how-to.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,11 @@
# Guidance on Accessibility
---
title: Guidance on Accessibility

tags:
- Accessibility
---

#

> _The power of the Web is in its universality. Access by everyone regardless of disability is an essential aspect._<br>
**Tim Berners-Lee, W3C Director and inventor of the World Wide Web**
Expand Down
10 changes: 9 additions & 1 deletion docs/implementing_RAP/code-review.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,12 @@
# Code review
---
title: Code review

tags:
- Code reviews
- Workflow
---

#

[![link to code quality comic image](https://imgs.xkcd.com/comics/code_quality.png)](https://xkcd.com/1513)

Expand Down
12 changes: 8 additions & 4 deletions docs/implementing_RAP/coding-best-practice.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,14 @@
---
#hide table of contents whitespace
hide: toc
---
title: Coding Best Practice

tags:
- Coding tips

# Coding Best Practice
hide:
- toc
---

#
You can find guidance on coding best practice at these pages:

General Code Development
Expand Down
15 changes: 14 additions & 1 deletion docs/implementing_RAP/example-pipeline.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,17 @@
# Example Pipeline (Python)
---
title: Example Pipeline (Python)

tags:
- Python
- Thin slice strategy
- Process mapping
- Project structure
- Loose coupling
- Open-source
- Coding tips
---

#

!!! tip "TLDR"
- This is an [example of a pipeline](https://github.com/NHSDigital/RAP_example_pipeline_python) made in Python with RAP principles in mind
Expand Down
15 changes: 13 additions & 2 deletions docs/implementing_RAP/how-to-publish-your-code-in-the-open.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,15 @@
# How to Publish your Code in the Open
---
title: How to Publish your Code in the Open

tags:
- Publishing code
- Transparency
- Workflow
- GitHub
- GitHub topics
---

#

In NHS Digital we have committed to publishing more and more of our code over time to **improve the transparency** of our analytical work.

Expand Down Expand Up @@ -72,4 +83,4 @@ Once a new publication's repository is published on GitHub, feel free to update
- [The benefits of coding in the open](https://gds.blog.gov.uk/2017/09/04/the-benefits-of-coding-in-the-open/)
- [Open source repositories by the Government Digital Service](https://github.com/alphagov)

*NHS England is not affiliated with any of these websites or companies.*
*NHS England is not affiliated with any of these websites or companies.*

0 comments on commit dba9f7e

Please sign in to comment.