Improve the "Tutorial" page

[iaindillingham]

To improve the "Tutorial" page, we will rework existing content into several new sections. We will not substantively change the existing content. However, we will: make the learning outcomes explicit; emphasize recent improvements to opensafely (i.e. opensafely exec); and group the next steps into two pathways.

The "Tutorial" page should:

• Make judicious use of screenshots. These need to be updated regularly.
• Present, but not discuss, a workflow.

The "Tutorial" page should avoid:

• information about Codespaces and dev containers in general. This needs to be updated regularly and is beyond our control.
• information about Codespaces opened outside a browser (e.g. opened in Visual Studio Code, JetBrains Gateway, JupyterLab). This needs to be updated regularly and is beyond our control.

There isn't a need to diff between new and existing files, so create a new file for each section and delete the existing file. Add a redirect to docs/_redirects, though.

If you're unsure what makes documentation good, or just unsure why I'm enclosing links in quotation marks, then read:

• "Best practices for GitHub Docs"
• "Style guide"

Introduction

• Learning outcomes (except for "Introduction" and "Next steps", they're the headings)
• System requirements ("All we need is an up to date web browser and an internet connection.")

Create a GitHub account

If you have a GitHub account, then skip to the next section.

• Choose a username
• Enable 2FA

Create a new repository

Create a new repository from the research template:

• The user should be the owner
• The name should be "opensafely-getting-started"
• The description should be "The OpenSAFELY getting started tutorial"
• The repository should be public

Create a Codespace

• Create a Codespace on the main branch

Generate a dataset for the first time

• Enter opensafely exec ehrql:v1 generate-dataset analysis/dataset_definition.py in the Terminal pane and press Enter
• Notice the patient_id and sex columns

Update the dataset definition

• Open the dataset definition
• Add dataset.age

Generate a dataset for the second time

• Enter opensafely exec ehrql:v1 generate-dataset analysis/dataset_definition.py in the Terminal pane and press Enter
• Notice the patient_id, sex, and age columns

Run the pipeline

• Open project.yaml
• Compare the opensafely exec command from the previous section to the generate_dataset action in project.yaml
• Open output and notice that it doesn't contain any files
• Enter opensafely run generate_dataset in the Terminal pane and press Enter
• Open output and notice that it contains dataset.csv.gz
• Explain that
  • opensafely exec runs a single action outside the pipeline
  • it's useful for getting feedback quickly
  • opensafely run runs a single action inside the pipeline
  • it describes how an action is run in the secure environment
  • Overlook the run_all action

Create a scripted action

• Create analysis/report.py or analysis/report.R
• Copy-and-paste the Python or R code

Add the scripted action to the pipeline

• Open the pipeline
• Add a generate_report action
• Enter opensafely run generate_report in the Terminal pane and press Enter
• Open output and notice that it contains report.png

Commit and push changes

• Create and push a commit from the Source Control pane

Check the tests pass

• Notice the action
• Notice the notification

Delete the Codespace

• Visit https://github.com/codespaces

Next steps

Application pathway:

• Link to "Onboarding new users to OpenSAFELY" (Catherine confirmed this document is still relevant.)

Learning pathway:

• Link to "ehrQL"
• Link to "Scripted actions"
• Link to "How to use Git" #45
• Link to "How to use Codespaces in your project" #38
• Link to https://jobs.opensafely.org/
• Link to "Introduction to Git in VS Code"