Documentation updates for researchers

[KatieB5]

Closes #433.

This PR updates the OpenSAFELY documentation, following changes to our processes around repo creation, transfer, and management, as part of #429.

Questions for reviewer(s)

1. Does the flow of the updated docs make sense?
2. Do we want to add a note to researchers in the "Default opensafely repository settings" section, to let them know they can request alternative settings e.g., require 'n' reviews on a pull request?

[cloudflare-workers-and-pages]

Deploying opensafely-docs with    Cloudflare Pages

Latest commit:	baa7b24
Status:	✅  Deploy successful!
Preview URL:	https://767e8378.opensafely-docs.pages.dev
Branch Preview URL:	https://katieb5-update-github-opensa.opensafely-docs.pages.dev

View logs

[StevenMaude]

summary: This is looking close to ready now. I've added some very small suggestions for you to consider.

Caveat: I reviewed entirely on GitHub, not on site preview, so maybe there are potential issues with formatting that I haven't caught. But I don't think there should be any, as the formatting is not complicated here.

I'm happy to have a another quick look through before merging, particularly if there's another round of edit and review by someone else.

[StevenMaude]

suggestion: Because this is in the "Getting Started" section along with the tutorial, perhaps it's worth briefly clarifying that a repository only needs to be in opensafely for real research purposes?

And not for just learning how OpenSAFELY works without needing access to real patient data. For that, you can keep the repository under your own personal account.

[KatieB5]

I've updated to clarify by adding 'research' in here: "To create a repository for your OpenSAFELY research project, you can either:"

I think as this is in the "How-to" guide, it's reasonable to assume people are referencing it because they want to create a real research repo. They're guided through the process of making a repo in their own account for the purposes of the tutorial, in the tutorial itself.

[StevenMaude]

On the specific questions:

1. Does the flow of the updated docs make sense?

It seems fine to me, but it's more difficult for me to pick up if we could make things clearer: I already know the process we're aiming at.

What I can say is that there is nothing clearly at odds against that process as I understand it.

2. Do we want to add a note to researchers in the "Default opensafely repository settings" section, to let them know they can request alternative settings e.g., require 'n' reviews on a pull request?

I've just added another comment in context there.

[lucyb]

It is important that the study repository is transferred into the opensafely organization, not forked into it.

Will researchers still have the ability to fork a repo into the opensafely organization or should this warning now be reworded?

[KatieB5]

That's a good question, and I'm not 100% sure. We haven't explicitly discussed forking, at least that I can remember. I would assume researchers won't be able to do this, as they're unable to create new repos within the opensafely org, and as I understand it (based on GitHub's documentation) you need this type of permission to be able to fork a repo.

Paging @StevenMaude for your thoughts/knowledge?

In terms of rewording, is it enough to remove the reference to forking?

[StevenMaude]

Will researchers still have the ability to fork a repo into the opensafely organization …?

I've not tested this. But I suspect the answer is no.

Forking a repository is effectively creating a repository that's part of a network with the original. So I think you would need to be able to create a new repository.

[StevenMaude]

@KatieB5's updated the text now, so this is done, I think 😃

[StevenMaude]

After I looked through the additional commit, I checked all the formatting on the preview version of the site. The formatting looks fine to me.

(I'm assuming there are only small changes now.)