fix: add a checklist and made a few edits

Signed-off-by: Christine <[email protected]>

Author: CBID2

website/library/reference/how-to-review-someone's-work.md

@@ -1,24 +1,52 @@
-# How To Review Someone's Work
+# How to be a great peer reviewer
 
 When you first start your technical writing journey, one of the many important skills you'll need to learn is how to do is peer reviews. It's a skill that will not only teach you how to collaborate with other technical writers and other people who interact with documentation, but it will also help you to become a better technical writer in the long run.
 
-## Peer Reviews vs. Code Reviews: What's the difference?
+## Tips for doing effective Peer Reviews
 
-Even though peer reviews and code reviews are often used interchangeably, there are some key differences between the two. Peer reviews are often more personal and more focused on the quality of the work, while code reviews are more focused on the quality of the code.
+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:
 
-## Tips for doing effective Peer Reviews
+### Content Review
+
+* **Overall structure and flow**:
+  * Are the steps in the correct order?
+  * Will the user be able to understand the steps?
+  * Have all the terms been defined at the first use?
+* **Accuracy and completeness**:
+  * Are all the steps accurate?
+  * Are there any steps missing or unclear?
+  * If you run through the document from start to finish, does it work?
+
+### Clarity and Readability
+
+* **Wording and clarity**:
+  * Is everything well worded?
+  * Are there any unclear bits?
+  * Can anything be made shorter?
+  * Does the tone suit the message?
+* **Formatting and consistency**:
+  * Are headings and subheadings used consistently?
+  * Are lists and tables used effectively?
+  * Are images and diagrams used to support the text?
 
-When it comes to peer reviews, there are a few things that you can do to make them more effective. Here are some tips:
+### Mechanics and Style
 
-- **Categorize the kind of feedback you're giving:** Use the feedback template to categorize the kind of feedback you're giving. For example, if you are asking the reader a question about the content, you would use the following template:
+* **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?
 
-```markdown
-[question]: what is the purpose of this section?
-```
+### Additional Checks
 
-This method will make it easier for the reader to understand what you're asking them to do.
+* **Links and references**:
+  * Are all links working correctly?
+  * Are references properly cited?
+* **Code and examples**:
+  * Do code snippets work as expected?
+  * Are examples relevant and effective?
 
-- **Be objective as much as possible:** Behind every piece of documentation is a person, so it's crucial to be mindful of your wording and tone when giving feedback. For example, if you noticed that a section is missing a code snippet or a key detail about the product, it would be ineffective to say, "This section stinks." Consider pointing out the strengths of the work and the areas that could be improved. For example, "this section describes the steps effectively, but the screenshots are missing alt text."
+## Conclusion
 
-- **Be clear and specific:** When giving feedback, be clear about what you're looking for. For example, if you noticed that the content is missing a code snippet, you should say, "this section is missing a code snippet." as opposed to "this section is missing content."
-- **Be concise:** While getting every detail correct is important, don't go overboard with your feedback. The person you're giving feedback might get overwhelmed with too much information. Keep it short and to the point. For example, if you're asking the reader to explain a concept, keep it to one sentence or two.
+The end goal of reviewing is to make sure that the work is a) correct/accurate, and b) the best version of itself (for now). The nature of online documentation is that it's 100% going to change at some point, so it's important to keep a good eye on the work as it's being written