Becoming SitePoint’s Peer Reviewer – How and Why
This document contains detailed instructions on how to do Peer Review, and what’s in it for you. Use these links to navigate to other parts of the documentation:
Reviewing helps your fellow authors. It helps us publish the highest quality work, and makes sure multiple pairs of eyes give us feedback on what may or may not be good or bad regarding a specific post. It also helps editors schedule your work faster (meaning you get paid sooner), and lets the channel editors see who’s interested in some “extracurricular” activities, and thus, potential benefits (some channels – PHP, for example – provide actual perks to authors who are active reviewers, but this will vary). Reviewing people’s posts helps everyone.
Once a draft PR is submitted, it will be given a label of
It will then have to be in
peer review mode for a specific amount of time or reviewed by a specific number of people before moving into
editor review stage:
The duration and number of needed reviews will vary per channel.
As a reviewer, you should aim to look at the posts that have only the
peer review label.
How do I review?
There are several different ways to review. Any one of them counts as a contribution and will bring you kudos points. See below for screencasts.
Issues – if you find a problem with, for example, an article that’s already been published, make an issue and point to it. Describe the problem, and someone will fix it. If the problem is outside the scope of the repository’s channel, use this public bug reporting repository.
If the article has the
peer reviewlabel, it is highly recommended you take a look at the post and voice your opinion in the pull request’s thread – no need to open separate issues, just address everything right there in the PR. When possible, tag the original author so they know they need to take a look at your suggestions. It’s the original author’s responsibility to update his post according to best practices recommended by others, whether this be language fixes, layout fixes, or code fixes. If you do a pull request on someone’s pull request, notify the author – by default, Github won’t notify them. If you aren’t familiar with PRs on PRs, ignore this part – just drop a comment in the original pull request of the draft instead.
Here’s how you drop a simple comment into someone’s submissions:
And here’s how you drop a comment on a specific part of their article:
Minor stuff – if you notice an image has a wrong URL, or a typo, or some formatting errors, no need to open an issue. Fix it and submit a pull request if the article is already merged into master or tag the author if not, everyone will appreciate it. For articles on which you can offer quick help, it’s best if you look for the appropriate lables. For example, the PHP channel has the need language help label for some posts – those will have faulty English or wrong phrasing. (You won’t be able to access the above link if you aren’t a member of the PHP channel’s repository).
Note that reviews don’t have to be full-on analyses of the posts (see Gif 1 above), they can also be just a read-through and feedback like “I like it” or “I like it, but I think it could be better if…”. Every extra pair of eyes is worth a fortune, so even small bits of feedback help a lot, and they shouldn’t take you more than 15 minutes per post, including reading.
How to pick posts to review?
Pick posts with the least amount of feedback. The more we can cover, the better. Also, posts that have open discussions, try to chime in and give your own opinions. Not just by posting “+1” but actually discussing the topic.
Generally, look through the pull requests, but prioritize those posts that are still under review. The older they are, the more important it is to review them.
How to accept criticism?
Don’t be offended when someone calls out mistakes in your post. Discuss them, voice your opinion, and ask others for feedback. Look at things from their point of view, keep an open mind, and be open to changes, updates and absorbing new knowledge. The ultimate goal is turning SitePoint into a repository of amazing and reliable content, and we can only do this together.
Are you trying to get us to do editors’ jobs for you?
It’s not like editors don’t do their usual work under Peer Review. They still have to review, quality test, and fix the post, as well as prepare it for publication with formatting and more. All we’re accomplishing with Peer Review is getting more eyes on posts before we publish, avoiding mistakes and preventing spread of misinformation. We’re enlisting the community for a quality boost and rewarding them for it. Literally everyone benefits from this.