website: add constructive peer review tutorial

Author: Sophie-Pages

website/library/reference/how-to-review-someones-work.md

@@ -0,0 +1,70 @@
+# 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.
+
+## What is a peer review?
+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.
+
+### 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, 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?
+
+## 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!). ”_
+
+<!---
+### 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?
+-->