website: add constructive peer review tutorial #254
Conversation
There was a problem hiding this comment.
Overall, really nice changes - I think this makes a lot of sense as a tutorial, with the template alongside.
I've left some general comments for your consideration, but nothing that I'd consider "blocking". Feel free to take or leave whichever pieces you like :)
I'll leave a pre-emptive approval (pending anyone else who wants to take a look)
| @@ -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. | |||
There was a problem hiding this comment.
I think the first sentence of this introduction feels superfluous here, but would make a really nice contextual snippet to introduce the page on the landing page it's linked from (adding this sort of introduction text on the landing pages can help them feel more "friendly").
The second sentence, imo, is strong enough to stand alone as a really strong introductory paragraph that tells the reader exactly what to expect from the page.
| # 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? |
There was a problem hiding this comment.
This section feels a bit at odds with the header. I think a more relevant header would be something like "Why should we peer review?" or "Why are peer reviews important?"
| ## 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. |
There was a problem hiding this comment.
It might be good here to include some practical tips for what "start with the positive" looks like in practice - by itself it feels a bit vague. You may want to include something like "Begin your review by highlighting the things the contributor did well, or by thanking them for their contribution". It might also be good to point to conventional comments or something like that
There was a problem hiding this comment.
I think it might also be good to point out here in this section that that doesn't mean one should only be positive - but that it's about framing any changes you want the contributor to make in a constructive way: that a) will make sense to them/are not arbitrary, b) are specific and actionable and c) are not negative/bashing. The examples you give in the following section are perfect supporting material for the general principles, but I think these principles should be clearly set out.
| **_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: |
There was a problem hiding this comment.
"from the general process" feels a little vague. I think it's actually fine to directly suggest that the reviewer's own processes share some of the blame for that (but in a constructive way). Perhaps something like:
"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 instruction in the original issue? Do they include all the relevant links a contributor might need? Are they explicit about what's expected? If not, this is a great place to look at making general improvements. Asking the contributor for feedback about their experience of contributing can also be really helpful, and will help to improve the experience for future contributors."
|
@Sophie-Pages, I've set up a redirect for the MicroCeph URL that was causing linkcheck to fail. |
|
Thank you once again @s-makin for your comments! I implemented them mostly as they are, with the exception of the Conventional Comments feedback. I decided to include the resource in a new Next steps section because I find the information there very clear and useful. I don't want to duplicate it in a way that would not do justice to the original work. By the way, I didn't know about Conventional Comments, so thanks for that! 😊 |
There was a problem hiding this comment.
All looks great to me, nice work @Sophie-Pages :) I can merge if you're happy, or if you're waiting on reviews from others I'll just leave it at an approval.
|
The linkcheck failure might be bogus, when I tested it just now the failing link was working, so running the CI again |
|
Hi @s-makin! Thanks! I think we can merge it, and if anyone would like to improve the page, then it would be a new issue :) |
That sounds good to me - I'll go ahead and do that |
Pull request for issue/225.
I focused my improvements on some of the goals of the initial request: “We'd like to document all of this from the reviewer's perspective, not just detailing the things to look out for, but also the approaches you should take, how to help contributors, how to reassure, and how to be constructive.” I believe my ideas could be extended upon but I focused on creating the new document structure and making it concise.
What is commented will be added into another document (cf issue/227). This other document will be a checklist of things to look out for during the review or editing process.