The new "How to use Git" page replaces the "Install GitHub and Git" page, as well as that page's entry in the "How-to guides" page. The new page should contain contextualized links to information about using Git with:
screenshots. These need to be updated regularly and are more suited to a tutorial.
a discussion of workflows. Researchers should decide whether to add then commit or commit --all; whether to checkout or switch; etc.
too much description or explanation. It should contextualise the links, but no more.
There isn't a need to diff between new and existing files, so create a new file 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:
Currently, the "How-to guides" page has a link entitled "How to use GitHub and Git" that points to the "Install GitHub and Git" page. This page contains instructions for:
installing GitHub Desktop
creating a GitHub account
requesting access to the OpenSAFELY GitHub organization
Confusingly, this page doesn't contain instructions for installing Git 😕.
Creating a GitHub account is covered by the "Tutorial" page (#44). Requesting access to the OpenSAFELY GitHub organization should be covered by the new starter checklist. Deleting this page feels too heavy-handed; reducing its scope, less so.
The new "How to use Git" page replaces the "Install GitHub and Git" page, as well as that page's entry in the "How-to guides" page. The new page should contain contextualized links to information about using Git with:
git. See the "Git Cheat Sheet" PDF.It should also contain links to more general information about using Git. Specifically:
The new page should avoid:
addthencommitorcommit --all; whether tocheckoutorswitch; etc.There isn't a need to diff between new and existing files, so create a new file 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:
Why are we doing this?
Currently, the "How-to guides" page has a link entitled "How to use GitHub and Git" that points to the "Install GitHub and Git" page. This page contains instructions for:
Confusingly, this page doesn't contain instructions for installing Git 😕.
Creating a GitHub account is covered by the "Tutorial" page (#44). Requesting access to the OpenSAFELY GitHub organization should be covered by the new starter checklist. Deleting this page feels too heavy-handed; reducing its scope, less so.