website: resolve review comments

Author: Sophie-Pages

website/library/tutorials/craft-a-constructive-peer-review.md

@@ -1,13 +1,15 @@
 # Craft a constructive peer review
-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. 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.
+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.
 
-## What is a peer review?
+## 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. It encourages them to contribute again.
+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.
@@ -23,14 +25,16 @@ Support your ideas with concrete examples and explain how to implement your feed
 **_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, think about what can be improved from the general process. Let’s say a contributor provided a document way below your expectations:
-* Were the task and its goal clear to begin with?
-* Were enough useful resources provided?
-* Could a template or style guide have helped?
+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
 

website/library/tutorials/index.md

@@ -1,8 +1,15 @@
 # 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>
+Craft a constructive peer review <craft-a-constructive-peer-review>:
 
 ```