The Documentation team uses GitHub to manage files. When we've completed a draft of a topic or chapter, we may ask members of the PM, engineering, or student support teams to review it for clarity and accuracy.
If you agree to review documentation, you'll need a GitHub account and permissions to add comments in the edx-platform and edx-ora2 repositories.
- To create a GitHub account, go to http://github.com.
- To get permissions to add comments, send an e-mail to support@edx.org. Include your GitHub username and specify that you want to be able to add comments to (not just read) the edx-platform and edx-ora2 repos.
When someone on the Docs team needs you to review files, the Docs member will tag you in a pull request. (A pull request is basically a way to ask permission to add files to the repo. The docs team will take care of adding the files after you're done reviewing them; you don't have to perform any other actions in the pull request.)
When you are tagged in a pull request in GitHub, you receive an e-mail that contains a link that takes you to the main page of the pull request. Near the top of the page you can see three tabs: Conversation, Commits, and Files Changed. To see the changes, click the Files Changed tab.
When you click the Files Changed tab, you can see each of the files that have changed, one after the other. If any image files have been changed, added, or deleted, these image files usually appear before the text files.
Scroll down past the image files and you'll see raw text files. Deletions are in red and insertions are in green.
If you want to make a comment, hover over the line you want to comment on until a blue comment bubble appears to the left of the line. Click the blue comment bubble and add your comment. The comment appears inline with the text.
If you don't want to wade through the raw text files, look at the title bar for the file. You'll see a Rendered button. Click this button to see an HTML view of the file. The only problems with this view are 1) you can't see images and 2) you can't make comments; you have to switch back to the raw text.
After you've added comments, the doc team will review the document, make any necessary changes, and ask you to review it again. When you don't have any more comments, switch back to the Conversation tab and add a "thumbs up" sign by typing :+1: (with the colons). (The "thumbs up" sign appears as soon as you type the first colon.)
Built HTML Documents
In addition to this version that you see in GitHub, the doc team sometimes creates a built HTML version that shows the documentation the way that it will look online. If so, the doc team will provide a link to the HTML output for the draft Readthedocs project in the pull request. You can view the HTML output, then go back to GitHub to make comments.