From 37be6272870ee2c35f1308cf3dfa2ca17fd2fd02 Mon Sep 17 00:00:00 2001 From: Sophie Pages Date: Thu, 3 Jul 2025 13:13:55 +0200 Subject: [PATCH 1/4] website: add constructive peer review tutorial --- .../reference/how-to-review-someones-work.md | 45 ------------ .../craft-a-constructive-peer-review.md | 70 +++++++++++++++++++ 2 files changed, 70 insertions(+), 45 deletions(-) delete mode 100644 website/library/reference/how-to-review-someones-work.md create mode 100644 website/library/tutorials/craft-a-constructive-peer-review.md diff --git a/website/library/reference/how-to-review-someones-work.md b/website/library/reference/how-to-review-someones-work.md deleted file mode 100644 index 6bbf7c9..0000000 --- a/website/library/reference/how-to-review-someones-work.md +++ /dev/null @@ -1,45 +0,0 @@ -# How to be a great peer reviewer - -The goal of reviewing is to make sure the content is accurate and the strongest version of itself—for now. Online documentation will change, so it’s important to stay focused as you write. - -One key skill to build early in your technical writing journey is peer reviewing. Offering your perspective to other writers can help make the content clearer and more useful for readers. Reviewing also helps you collaborate effectively with other writers and stakeholders, and it strengthens your own writing over time. - -## Tips for doing effective Peer Reviews - -When it comes to peer reviews, it can get confusing and overwhelming at times because you want to be effective, but at the same time you don't want to give too much feedback to point that the TA is confused. Consider using this checklist of things to keep in mind when doing peer reviews: - -### 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? diff --git a/website/library/tutorials/craft-a-constructive-peer-review.md b/website/library/tutorials/craft-a-constructive-peer-review.md new file mode 100644 index 0000000..efc5923 --- /dev/null +++ b/website/library/tutorials/craft-a-constructive-peer-review.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!). ”_ + + \ No newline at end of file From fe7bc7b37a664ff679a07d45a3e905ae03746ff6 Mon Sep 17 00:00:00 2001 From: Sophie Pages Date: Fri, 4 Jul 2025 16:56:21 +0200 Subject: [PATCH 2/4] website: update toctree --- website/library/index.md | 1 + website/library/reference/index.md | 1 - website/library/tutorials/index.md | 8 ++++++++ 3 files changed, 9 insertions(+), 1 deletion(-) create mode 100644 website/library/tutorials/index.md diff --git a/website/library/index.md b/website/library/index.md index ce069aa..83fb4ed 100644 --- a/website/library/index.md +++ b/website/library/index.md @@ -48,5 +48,6 @@ This section is currently under development. If you'd like to contribute, please :maxdepth: 2 Reference +Tutorials ``` diff --git a/website/library/reference/index.md b/website/library/reference/index.md index dccb27d..a1fbe19 100644 --- a/website/library/reference/index.md +++ b/website/library/reference/index.md @@ -4,7 +4,6 @@ :maxdepth: 1 Links for technical writers -How to review someones work How to implement peer reviewers feedback ``` diff --git a/website/library/tutorials/index.md b/website/library/tutorials/index.md new file mode 100644 index 0000000..4392f17 --- /dev/null +++ b/website/library/tutorials/index.md @@ -0,0 +1,8 @@ +# Tutorials + +```{toctree} +:maxdepth: 1 + +Craft a constructive peer review + +``` From 5b1d770b4475ffbe86c7d5c93f2158d5d151e74a Mon Sep 17 00:00:00 2001 From: Sophie Pages Date: Sun, 20 Jul 2025 23:25:34 +0200 Subject: [PATCH 3/4] website: resolve review comments --- .../craft-a-constructive-peer-review.md | 18 +++++++++++------- website/library/tutorials/index.md | 9 ++++++++- 2 files changed, 19 insertions(+), 8 deletions(-) diff --git a/website/library/tutorials/craft-a-constructive-peer-review.md b/website/library/tutorials/craft-a-constructive-peer-review.md index efc5923..e5d8d43 100644 --- a/website/library/tutorials/craft-a-constructive-peer-review.md +++ b/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/). +