Skip to content

Commit

Permalink
fix(style guide): peer editing workflow
Browse files Browse the repository at this point in the history
  • Loading branch information
zuluecho9 committed Feb 8, 2022
1 parent 7ded8b7 commit d0f8c0b
Showing 1 changed file with 26 additions and 5 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -7,22 +7,43 @@ redirects:
- /docs/style-guide/writer-workflow/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](/docs/style-guide/writer-workflow/tech-writer-workflow/) for info on how to set up your local environment. To troubleshoot GitHub issues, see [our guide](/docs/style-guide/writer-workflow/github-troubleshooting/).
Use this document to learn how to review and peer edit docs for your fellow writers in GitHub. Check the [Tech Writer workflow doc](/docs/style-guide/writer-workflow/tech-writer-workflow/) for info on how to set up your local environment. To troubleshoot GitHub issues, see [our guide](/docs/style-guide/writer-workflow/github-troubleshooting/).

## When to get a review [#when-to-get-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
* Avoid violations of 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 [#peer-edit]

If youre 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.
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 [#edit-pass]

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

1. Open the PR that youre assigned to review.
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 doesnt require follow up.
- **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. Youll be notified with any updates that the writer makes.
- **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.

Expand Down

0 comments on commit d0f8c0b

Please sign in to comment.