Improve the Getting Started Tutorial

StevenMaude commented 4 months ago

The goal here is to simplify the Getting Started tutorial enough such that the user's path through it has fewer possibilities for there to be ambiguity of what to do. This makes it easier for us to help guide them to have a completed Codespaces tutorial project, that covers the use of OpenSAFELY, to the point of getting working research code on GitHub.

The tutorial is intended to introduce researchers to key concepts about the OpenSAFELY platform, including ehrQL (extraction code), analysis code and running it via the cli (the pipeline).

We should expect someone to complete this tutorial in approximately 30 minutes.

Tasks

From the session with Catherine (#4), we observed some potential improvements. Some or all of these improvements might be made, for this issue to be complete. It maybe that we do not want to implement all of them, so they should be considered first.

Focusing the guide more on Codespaces than local installation

[x] #40
[x] #39 (We may need a separate page that describes more on this. (The local installation content all probably needs reviewing too, but this is out of scope for this issue.) That's this documentation issue: opensafely/documentation#1396)
[ ] ~Refer to the possibility of local installation, but only briefly — possibly only at the end? — and link to a page that describes more on that.~ Mention in the top-level getting started guide, not the tutorial.
[ ] ~State that we are using Codespaces for this tutorial, and perhaps suggest that Codespaces alone might be sufficient for some preliminary work with OpenSAFELY, particularly for ehrQL.~ Mention in the explanation section of the getting started guide, not the tutorial.
[x] Remove any mention of Docker. opensafely/documentation#1485

General context

[x] Make the motivation for the tutorial more obvious: why are you doing the tutorial, and what will you get out of it (a completed study that would be ready for submission to OpenSAFELY Jobs, and some idea of what the end-to-end OpenSAFELY process is like, up until OpenSAFELY Jobs)?
[x] ~"This tutorial is, therefore, a very fast tour…" is an important point, but buried.~ The text is removed now.
[x] ~What's a demonstration research study? Why does the user care about this?~ The text is removed now.
[x] Some of the section headings don't make sense for Codespaces; "clone the study code to your computer". opensafely/documentation#1485
[ ] We could add a diagram — created via Mermaid markup? — like the one Catherine suggested to explain how GitHub, Codespaces, the user repository all fit together — this might better fit in an explanation page

Repository setup

[x] Update the screenshot so that the repository is being created in the user's account, not in the opensafely org.
[x] Provide a suggested name for the repository. opensafely/documentation#1503
[x] Can we remove the "deleting head branches" step? It's an extra step that isn't immediately obvious what to do, or what the purpose is. opensafely/documentation#1503
[ ] We talk about "initialisation" but there are actually three initialisation steps: creating the repository from a template, the template's setup workflow running to edit the README, and setting up a codespace.

Codespaces

[ ] Can we use a diagram with text and arrows to explain the layout of a codespace, instead of text?
[x] We warn that the user may not be able to access Codespaces. Do we need this warning, or should we add it at the point at which the user tries to open a codespace.
[x] We tell the user to check which directory they're in. In Codespaces, you shouldn't need to check which directory you're in, inside the terminal, because it defaults to the location of project.yaml. opensafely/documentation#1485
[ ] Consider mentioning that the codespace will have a random two word name.
[ ] Explain deleting the codespace inline in the Getting Started guide, instead of redirecting the user elsewhere.

Updating screenshots

[x] We ask the user to create a working repository under their own account, but the screenshot shows the opensafely organization as owner.
[x] The "include all branches" option has moved, so the screenshot needs updating. Do we even need to mention this at all? It's good general practice — the research-template branches aren't generally useful to researchers — but doesn't really have any impact on the tutorial, and is an extra step.

Copy-pasting

[x] Be consistent in how we arrange commands to run; there was at least one, which seemed like it was inline. Maybe all the user commands should be in separate code blocks, and not inline.
[x] Decide and be consistent in how those commands are written. Do we include the terminal prompt, or not? If we do, it might make it more obvious that it is a terminal prompt. But copy-pasting then requires a manual edit at the command-line to remove the copy-pasted prompt symbol. It may be simpler to only include the command, and instruct users to copy-paste to the prompt. (I think copy-pasting is fixed following opensafely/documentation#1461.)
[ ] Consider warning the user about the browser or VSCode asking about clipboard permissions. Edge warned about this, and VSCode mentioned about "key bindings".
[ ] We might avoid some user copy-pasting by mentioning scrolling through terminal command history with the cursor up.

Working on the example code

[x] The initial run of the ehrQL produces 10 rows, not 500 as mentioned in the text.
[x] We could show users how to check on the status of the template setup workflow.
[x] It wasn't clear whether the user should re-inspect the .csv.gz after adding the age column; maybe we should tell users to do this specifically. They can see the new column.
[ ] For the additional Python/R analysis code, the two tabs can make it confusing as to which of these you're looking at. It might be better to inline both examples.
[x] The colour of the commit button for users may differ from that in the screenshots.
[x] Give a better explanation on steps for saving the commit message and completing the commit.
[x] Review what we write about "sync changes" means, and consider explaining it more.
[ ] The automated tests for the Getting Started research code may have already completed by the user gets back to the GitHub repository page. We should warn about this.

Analysis code

[x] Support only Python or R for the analysis. opensafely/documentation#1485
[ ] Include an info box for supporting Stata in the researcher's analysis outside of the tutorial.

Addressing other sources of potential confusion

[x] Should we mention about two-factor authentication? Do GitHub nudge their users towards this anyway? We left this in as advice.
[ ] Consider removing mention of the Q&A forum, which has had minimal activity. More support questions tend to happen on Slack now. (Although not all people completing the tutorial may have access to Slack.)
[ ] Mention what ehrQL is, inline with where we first mention it (we only link to a page describing it).
[x] We could make the next steps following the completion of the Getting Started guide clearer. Which order of things should the user learn next? opensafely/documentation#1503
[x] Remove the link in "Next steps" to the os-demo-research notebook which uses cohort-extractor. opensafely/documentation#1503
[x] Remove the mention of "Right now you can only use this to run real jobs, but we're working on adding the ability to test your repository against dummy data." unless we are planning on implementing this. opensafely/documentation#1503

Typos

[x] "create new repository based from our template" should be "create a new repository based on our template"
[x] 'and line 15 "*Give me a column of data' — the formatting is broken here because of the lack of a closing asterisk.

Jongmassey commented 4 months ago

Should we mention about two-factor authentication? Do GitHub nudge their users towards this anyway?

I think we should at least prepare new GitHub users for the fact they're going to have to/be prompted to set up 2FA

lucyb commented 3 months ago

I think we should at least prepare new GitHub users for the fact they're going to have to/be prompted to set up 2FA

We do at the moment and I think we should continue to mention it (and strengthen our wording around it).

It might be worth noting that the ehrql guide also mentions needing a GitHub account, but doesn't mention 2FA.

StevenMaude commented 2 months ago

I'm not sure if doing everything here is worthwhile, if we're replacing the tutorial. But some of it is being done anyway as part of tidying things up in opensafely/documentation#1485.

StevenMaude commented 1 month ago

I updated the task list following merging of opensafely/documentation#1503, which addressed some of the points here.

lucyb commented 3 weeks ago

Given that we've now addressed the majority of the points here, is it worth closing the ticket? We can always create new tickets that address some of the specific points if they come up again.

StevenMaude commented 3 weeks ago

@lucyb: I think that's a fair and reasonable point. We did most of this, a lot with restructuring the tutorial.

opensafely-core / codespaces-initiative