How to work on documents together
There's a file on Github somewhere, and you'd like to edit it and post a new version. For example a Chemdraw file where you'd like to change the structure of a molecule.
With a Github account you should be able to download the file from the relevant repository ("repo"), modify it and upload a new version (renamed file).
If you can't, you need to be given extra permissions. Ping an admin person.
But doing this directly means you miss out on a powerful aspect of Github, which is able to keep all previous versions of a file without the need to change the filename, and includes a "checking" step before your version of the file is accepted. This helps quality control.
This is a guide on how to get involved in editing OSM files on Github.
Find the repository containing the file that you're interested in (let's say it's a Chemdraw file called "Tester"). Let's say we've spotted a mistake in a diagram in the wiki for Series 4 and need to add a methyl group to the structure. So we go to the Series 4 repo, containing all the wiki files, and we need to get all these files onto our laptop. So we download the repo to the Desktop client by clicking on the relevant button:
The software puts all the repo files onto your hard drive where you specify. This version is the Master version of the repo. Now what you can do is open and modify the file you want, save it (same file name, just save it), and then replace the online file with your new version directly. To do this you go to the Github desktop client, which will have noticed that you altered a file, and you just "Commit to Master" (with a comment as to why)
and then click "sync".
Hey presto the online file is updated for all to see.
But this is not great. Nobody is alerted to the change you made and nobody checks it. So you should only do this if you're the only one working on a file and you're absolutely certain that the change is fine.
Much better is to use Pull Requests.
To work collaboratively you should first create your own branch of the repo. You can do this in the Desktop client - there will be some option with a symbol a bit like this.
You should now be able to commit your change (your modified file, same filename) to this branch, and then "sync" or "publish" this branch to the website. An alert will appear that there is a "pushed" branch, and you'll be offered the option to compare the branches.
Click that button, and you'll be taken to a screen where you can generate the pull request, by adding a comment (useful, explaining what you did).
Hopefully the branches can be merged (i.e. there are no conflicts anywhere). Notice how the Master is being compared to your branch. Click to generate the Pull Request. This generates the alert that this change needs to be approved by someone.
The Request appears in the Pull Request tab. There should be a green button allowing you to approve the merge of your branch to the Master.
If there are problems with the change, comments can be made at the bottom of the page. There are a whole bunch of review options at this point. When you click "merge" you may be asked for confirmation, and then it's done.
If that's all you want to do, you can delete your branch, but if you are likely to want to carry on making changes, keep your branch going.
All previous versions of a file can be found by clicking on the file (on the website) and going to the "history" button.
There may be other ways in which you find you have options to create pull requests, if you edit files directly on the website:
Again, unless you're sure that you know what you're doing, or the change is minor/uncontroversial, don't commit directly to the Master.