How to Peer Review a Guide
Guides Project
CoPs Members Guide Orientation
Table of Contents
Guides Project
Learn from Peer Reviewing a Guide
What is the goal of peer review?
The peer review process aims to identify any content missing from a guide or problems with its instructions
Personal Benefit
By following a guide, you’ll learn how to do something new and add editing experience to your resume
Organizational Benefit
Your perspective helps make sure our guides are relevant across our community and make sense to anyone who uses them.
Improve the accuracy and applicability of the information across projects.
Guide Benefit
Reviewing a guide ensures it is mistake-free and easy to understand for someone new to the process or practice
Guides Project
How to Select a Guide to Peer Review
STEP 1�Choose a Guide from your CoP’s board with the label ‘TG: Review Guide’ or ‘Guide: Needs Peer Review’
Guide Picking Tips:
�My project will benefit from this process�
I have no experience/I would like to be able to add the process to my resume and skill set.
I want to review a guide from someone else who reviewed a guide I created.
Guides Project
How to Select a Guide to Peer Review
STEP 2�Assign yourself to the Guide issue and move it to the ‘In Progress (Actively Working)’ column
Guides Project
Communicating Your Assignment
STEP 3
Add a comment to the issue @ messaging the author to let them know you are going to peer review their content and when you expect to finish your review
Guides Project
Assessing the Guide
Guides Project
Guides Project
Checking the Guide Against the Template
STEP 1�Compare the sections of the guide to the sections on the template
The guide should include all of the sections from the template. If it does not, add a comment to the guide document highlighting the missing sections.
If the guide includes sections not listed on the template, make a note of this as well. If the template would benefit from the addition of this section, you can suggest it here:
Guides Project
Reviewing the Guide’s Content
STEP 2�Assess the clarity of the guide
Follow the guide from start to finish as best as you can. If the instructions are unclear or do not lead to the expected result, make comments on the document where it needs improvement.
You should also bring up any questions that you have when using the guide, and any suggestions for content to add.
What to Consider
Guides Project
Comment Etiquette
The goal of your comments should be to improve the guide and create a dialogue with the author. Ask questions and be clear about what exactly the issues you are having are.
Remember that the author is a person who put a lot of effort into writing the guide and will see your comments. Be kind and constructive with your criticism.
Instead of:
“This doesn’t make any sense.”
“You shouldn’t have done it this way.”
Try:
“I’m having trouble following this step. Could you go into more detail about the process here?”
“I think this would be clearer if you used X as an example instead of Y.”
Guides Project
Communicating with the Author
Guides Project
Guides Project
Notifying the Author of Review Completion
When you complete your review, @ the author on the issue comment letting them know you are done and if you have left any comments on the document.
It's also a good idea to ask if they have any questions.
Guides Project
Responding to Author Questions
If the author has questions about your review, acknowledge that you have seen the questions by @-ing them in a comment on the issue. Give them a date by which you can get back to them with an answer.
You may have to go back and forth with them a few times before their questions are fully resolved.
If you cannot come to a resolution with the author, ask other members of your CoP to weigh in.
Guides Project
Wrapping Up Your Peer Review
After you have finished your review and answered any questions from the author, unassign yourself from the issue.
To get credit for your contributions, add your name to the list of contributors at the end of the guide document.
Guides Project
🎉 Congrats!
You have successfully learned how to peer review a guide!
Guides Project
Next Steps
You are here
Next step in your guide making process
Guides Project
List of Instructional Slides
Guides Project
Q&A
Q&A
Guides Project
Guides Project
Q&A - What are your Guide pain points
Self Guided or Video tour
Add your questions to the ____ issue #
In person Discussion and Chat questions/answers
Q:
A:
Q:
A:
Q:
A:
Q:
A:
Guides Project
Contributors
Peer created guides are an important part of Hack for LA’s Culture. Help us to make it better by posting any comments directly next to the content.
How to Peer Review a Guide was created and contributed to by:
Bonnie Wolfe
Sarah Edwards
Guides Project
Guides Project