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-documentation repositories.

• To create a GitHub account, go to http://github.com.
• To get permissions to add comments, go to https://employees.edx.org/support. Include your GitHub username and specify that you want to be able to add comments to (not just read) the edx-platform and edx-documentation repositories.

Identifying Yourself on GitHub

GitHub tagging (@name) relies on usernames. If you don't know someone's username, but you DO know their first and last names, GitHub will try to find the right user name. So, it's really really helpful to add your first and last names to your GitHub profile.

1. Go to www.github.com and sign in. (If you don't have an account, create one now!)
2. There's a non-obvious menu that lets you fill out information about yourself.
   
   
   
   
3. Select Your profile.
4. Select Edit profile.
   
   
   
   
5. Fill in your name.
6. Optional: upload an image, etc.
7. Select Update profile.

This will be super helpful to others working with you to get your input.

Reviewing Files in GitHub

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 repository, or 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.)

1. 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.
2. To see the changes, click the Files Changed tab.
   
   
   
   
3. When you click the Files Changed tab, you can see each of the text files that have changed, one after the other. If any image files have been changed, added, or deleted, these image files appear separately from the text files.
4. In text files, deletions are in red and insertions are in green.
   
   
   
   
5. If you want to make a comment, move your cursor to the start of the line you want to comment on. A plus sign icon appears.
   
   
   
   
6. Click the icon and add your comment. When you select Comment, your comment appears inline with the text.
   
   
   
   
7. If you don't want to wade through the raw text files, look at the title bar for the file. You'll see a View option. 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 use your browser's back button to go back to the original, find the line you want to comment on, etc.
8. After you've added comments, go to the Conversation tab and enter a general comment like, "I finished my review". The doc team will review your comments, make changes, and probably ask you to review it again.
9. When you don't have any more comments and think that every looks pretty good, add your thumbs up on the Conversation tab. To add a "thumbs up" sign type :+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.