Peer editor workflow

Use this document to learn how to review and peer edit docs for your 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.

When to get a review

Almost all PRs to the docs site from a tech writer should receive a review from a fellow tech writer. We do reviews in order to:

• Catch inaccuracies
• Fulfill our style guide
• Improve our writing, particularly voice and tone
• Get a different perspective (for example, learning about something related to the work that was unknown)

Reviews are important, and the default should be to always get a review! With that in mind, if you're confident that your PR is small in scope and unlikely to benefit from the considerations above, you can merge your PR without review. Regardless of whether you get a PR review, it's your responsibility as a writer to ensure your PR builds correctly and passes all technical checks.

Some examples of things you might decide to merge without review:

• Fixing broken links
• Changes to just a few words or lines of a doc
• A simple search and replace of a word/phrase you're confident is simple and unproblematic
• A particularly time-sensitive edit (in that case, you may decide to get a review later)
• Changes you made in response to a PR review that you think don't need an additional review.

If you're in doubt at all of whether to get a review of your PR, get one.

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.