Encourage researchers to update the README

lucyb commented 2 years ago

User story

As a researcher I want it to be straightforward for me to create at least a minimum acceptable README on my repo, and update it as required prior to making that repo public, so that it is useful to other researchers and the public.

Background info

Currently when Amir emails users to ask them to agree to making their repo public, he points them to these instructions on updating their README
Currently README.md is mentioned in Publishing your GitHub repository
Currently a README is automatically generated when you create a repo from the research-template repo
Likely that we will need some of Steve’s time - we will need to agree this with the Data Team
We have confirmed with Amir that he doesn’t need to check each README before making the repo public - if the researcher has said that it meets the requirements then he believes them. EDIT: in a meeting on 28/09/22 Amir asked that someone from OpenSAFELY checks all readme files before making a repo public (not necessarily him) - this is covered in a separate issue re. approval

Acceptance criteria

A template README that contains a single link to a page on the Jobs site from where people can get to the info they need (that was previously within the readme) - NEEDS SPIKE TO CHECK THIS IS POSSIBLE
Somewhere on jobs site for researchers to complete all the essential aspects (as agreed with Amir and Seb):
- Project status (ongoing/complete/etc... - see gdoc link above)
- Description for project status (place to explain why abandoned/put in links to published papers etc)
- Purpose/description for each workspace
Documentation:
- Documentation that explains what each status, project-level description, and workspace-level description should contain, and when it should be added/changed. Examples...
  - For complete/ongoing: Description and links to publications/reports/other external outputs arising from this project
  - For abandoned: Text describing why
- Remove section on README from gdoc that Amir uses (see link above)
- Edit Publishing your GitHub repository to reflect the new process (ask Steve for help/advice on this, as that page needs more than just a tweak!!)
- Put new README into template from which new repos are created
Update separate user story on prompting users to agree to make their repo public to include the following acceptance criteria: users must also confirm that they have updated the information in Job Server as described above
The template/guidance/process has been tested with researchers/projects (ideally with different ways of organising their repos/workspaces/projects)

Implementation Ideas

IDEA to attempt to fail fast: mock up process for Will to try out completing the info needed for a project with lots of workspaces [NO PROMPTING OR HELPING HIM!] - can he do it? Is it confusing?... And is it ok for Amir?
? For key steps, prompts to users (e.g. when change status to completed, prompt to add links to publication)

Related Tickets

lucyb commented 2 years ago

For reference, for anyone picking up this ticket. I have a branch with some wording changes on it for encouraging users to make repos public. It shouldn't conflict with any changes required here, but may be useful to be aware.

lucyb commented 2 years ago

@brianmackenna has suggested pointing to one or two repos as examples of best practice READMEs. This sounds like it would be really useful to researchers and maybe reduce the amount of description required about what a good README looks like.

lucyb commented 1 year ago

Need to discuss this before starting work, as the requirements have changed

opensafely / research-template