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.