Skip to content

011924: update review recommendations to improve guidance #509

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jan 22, 2024
Merged

011924: update review recommendations to improve guidance #509

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6b8ae4f
011924: update review recommendations to improve guidance
Jan 19, 2024
695e307
grammar fixes
Jan 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 16 additions & 10 deletions REVIEWING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,32 +5,38 @@ Contributions to the set of documents in this repository can receive reviews fro
1. A **copy review**, which focuses on information structure and wording; typically performed by a MongoDB Documentation Team member
2. A **technical review**, which addresses code snippets and the technical correctness of prose; typically performed by a MongoDB engineer.

# Which Types of Changes for which to Request a Technical Review
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added this section to make it more clear when to request a technical review.


- When the PR changes include code snippets.
- When the PR changes include release notes, breaking changes, or upgrading versions.
- To get alignment on specific wording of descriptions of technical information, especially for new features.
- If in doubt, request a technical review.

# What to Review

See the following sections for reviewer expectations for each type of pull request (PR) review:

## Copy Review

Review the structure, wording, and flow of the information in the PR, and correct it if necessary.
A typical copy review consists of the following checks:

### What to Review

- Wording
- Wording, including grammar and spelling
- Page structure
- Technical content to the extent of the reviewer’s understanding.
- Technical content to the extent of the reviewer’s understanding
- Whether the PR fulfills the Acceptance Criteria described in the
linked JIRA ticket.
linked JIRA ticket

### What Not to Review

Nothing is completely off-limits to a copy review of a PR -- if you notice a technical issue, it's best to call it out early.
Copy reviewers should constrain their reviews to content within the scope of the JIRA ticket, or otherwise create PRs to address anything unrelated.


## Technical Review

Review the technical accuracy and completeness of a PR and correct it if necessary.

### What to Review
A typical technical review consists of the following checks:

- Technical accuracy
- Release notes, breaking changes, and upgrading pages; ensure the technical claims are correct.
- Code snippets; ensure the code is idiomatic and that all technical claims are correct. e.g. ("To create a `Foo`, use the `Bar.createFoo()` method")
- Problematic explanations that could trip up users who try to follow the documentation.

Expand Down