Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
1 change: 1 addition & 0 deletions website/library/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,5 +48,6 @@ This section is currently under development. If you'd like to contribute, please
:maxdepth: 2

Reference <reference/index>
Tutorials <tutorials/index>

```
45 changes: 0 additions & 45 deletions website/library/reference/how-to-review-someones-work.md

This file was deleted.

1 change: 0 additions & 1 deletion website/library/reference/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@
:maxdepth: 1

Links for technical writers <links-for-technical-writers>
How to review someones work <how-to-review-someones-work>
How to implement peer reviewers feedback <how-to-implement-peer-reviewers-feedback>

```
74 changes: 74 additions & 0 deletions website/library/tutorials/craft-a-constructive-peer-review.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
# Craft a constructive peer review
The approaches you will learn in this tutorial can be applied to peer reviews on documentation and can be used to improve your feedback on any topic.

## Why are peer reviews important?
A peer review is about making sure the content is the strongest version of itself—for now—while also making contributors feel valued and supported. It is a key skill to build early in your technical writing journey. Offering your perspective to other writers helps make the content clearer and more useful for readers. Peer reviews also help you collaborate effectively with other writers and stakeholders, and they strengthen your own writing over time.

## How can I make my peer review constructive?

### Start with the positive
Start with the positive to create an environment where people feel valued and to encourage them to contribute again. You can begin your review by highlighting the things the contributor did well, or by thanking them for their contribution.

"Starting with the positive" doesn't mean one should only be positive. It is all about framing any changes you want the contributor to make in a constructive way. In the following sections, you will learn more about how to make your feedback comprehensible, specific, and actionable.

### Focus on the document
When proposing improvements, focus your feedback on the document, the task, or the users, and not on the person. See how those two sentences feel different: _“**You** didn’t clarify this aspect.”_ and _“**The document** doesn’t clarify this aspect.”_ With this approach in mind, you reduce the risks that contributors may feel attacked or demotivated by your feedback.

On the other hand, it is usually fine to talk about the person when giving positive feedback: _“I like how **you** approached this particular aspect.”_

### Explain your reasons
Provide guidance and explain the reasons why you are proposing changes. It helps contributors learn, and they will be able to spot mistakes or improvements by themselves in the future.

### Provide concrete examples
Support your ideas with concrete examples and explain how to implement your feedback.

**_Note_**: Be mindful of the number of concrete examples you provide. Sometimes one or two key examples are enough to set the contributors up for success without overwhelming them.

### Don’t forget the bigger picture
Lastly, if you received a contribution that fell way below your expectations, it may be that there are improvements you can make in your contributor workflows. For example, are your README and contribution guidelines clear enough? Did you provide enough instructions in the original issue? Do they include all the relevant links a contributor might need? Are they explicit about what's expected? If not, these questions are a great place to start with to make general improvements.

Asking the contributors for feedback about their experiences of contributing can also be really helpful, and will help to improve the experience for future contributors.

## Summary
When you put what you’ve learned so far into practice, a constructive peer review may look something like this: _“Thank you for your contribution, I like how you [**positive feedback**]. Additionally, **our users** would benefit from having this aspect explained because [**reasons**]. Here is how I would apply it: [**concrete example**]. Lastly, you can take a look at our **style guide** that I forgot to link in the initial issue (sorry for that!). ”_

## Next steps
If you are interested in learning more about how to format, label, and decorate your feedback, we encourage you to read about [Conventional Comments](https://conventionalcomments.org/).

<!---
### Content Review

* **Overall structure and flow**:
* Are the steps presented in a logical sequence that guides the user effectively?
* Is the language simple for the user to understand?
* Have all the terms been clearly defined?
* **Accuracy and completeness**:
* Does the document present any information that could be unclear or misleading to the user?
* Are all steps accurate and free from mistakes?
* Do the steps' code snippets work when followed?

### Clarity and Readability

* **Formatting and consistency**:
* Are headings and subheadings used consistently?
* Are lists and tables used effectively?
* Are images and diagrams used to support the text?

### Mechanics and Style

* **Spelling and grammar**:
* Are there any spelling or grammar errors?
* Are punctuation and capitalization consistent?
* **Style and tone**:
* Is the tone consistent throughout the document?
* Are there any areas where the tone could be improved?

### Additional Checks

* **Links and references**:
* Are all links working correctly?
* Are references properly cited?
* **Examples**:
* Do the real-world examples effectively enhance the understanding of the documentation's topic?
* Do the real-world examples resonate with the user?
-->
14 changes: 14 additions & 0 deletions website/library/tutorials/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# Tutorials

## Peer reviews

Whether you are an experienced peer reviewer or someone wanting to give a peer review for the first time, this tutorial will help you craft constructive feedback:
- [Craft a constructive peer review](craft-a-constructive-peer-review)

```{toctree}
:hidden:
:titlesonly:
:maxdepth: 1

Craft a constructive peer review <craft-a-constructive-peer-review>
```