Peer editor workflow

Use this document to learn how to review and peer edit docs for you fellow writers in GitHub. Check the Tech Writer workflow doc for info on how to set up your local environment. To troubleshoot GitHub issues, see our guide.

Peer editing workflow in GitHub

If you’re peer editing a doc or have been otherwise assigned to a PR as a reviewer, you have a few choices for how and where to do the work. The most streamlined and open-source approach is to do the edit using GitHub options, rather than copying the file to Google Docs and editing there.

Developmental edit pass

For cases where you have questions and suggestions rather than straight copy edits, follow these steps.

1. Open the PR that you’re assigned to review.
2. On the Files changed tab, you can either:
   • Click Review changes and then select one of the following:
     • Comment - use if you have a comment that doesn’t require follow up.
     • Approve - use if you just want to approve the PR. You can request changes in the Leave a comment area, and select Approve if you want to let the writer make the edits and merge the file without a follow-up review from you.
     • Request changes - use for times when you want to make sure the changes you request are included. You’ll be notified with any updates that the writer makes.
   • OR, start making comments on lines or sections of the doc. To do this, click the add comment icon , and leave an edit or comment for that specific line in the page. With this option, you get the choice between adding a single comment or starting a review. If you’re going to make comments throughout a doc, choose Start a review so the comments will all be rolled into one commit.
3. Click Finish your review to complete your review. This triggers a notification to the writer alerting them that you’ve made suggestions.

Copy edit workflow

If you have copy edits for a file rather than comments and suggestions, you can make the changes to the file in different ways. Here are two main options:

1. Edit using the GitHub browser: On the Files changed tab, in the diff window click the editing button (three dots). When you finish your edits, add a comment at the bottom of the file and choose to either commit the changes directly, or create a branch and start a pull request. Choose to branch and start a pull request if you expect a writer to review the diff and accept or revise your edits.
2. Edit locally: Check out the branch containing the file you want to edit. In GitHub Desktop, click the Current branch down arrow and select the branch. Then, make the edits on your local drive, save, and commit your changes to the branch.
   • Note that this approach adds your edits to the open pull request. You can now see the changes you added to the file on the Files changed tab in the PR.

These are just a few of many editing options. You’ll find your preferred way, just as with any other tool.