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?