Behind the Scenes: A Look at SitePoint’s Peer Review ProgramBy Nilson Jacques
What is Peer Review?
More from this author
You might be familiar with the term ‘peer review’ from the world of science research. The majority of reputable scientific journals operate a peer review system to vet the research papers that are submitted for publication. Several scientists who are familiar with the topic of the paper are asked to read it over and look for any potential errors or omissions and make recommendations for corrections and improvements that ultimately should result in a higher-quality publication.
Our peer review system works on a similar basis. Once a draft article is submitted to us, we try to seek out at least two people from our pool of volunteers who can read it and provide some feedback to the author.
Drafts are submitted as pull requests to our article repository on GitHub, which allows reviewers to comment on specific sections of the article and chat to the author about suggested changes. This has often lead to some very productive conversations in the comments and pushed a good article to become truly great.
Although we have some really great reviewers helping us out, it can be difficult getting enough reviews for the articles we receive. There’s a limit to how much we can ask of someone (especially as they’re doing this in their spare time), and it can be difficult to match up an article with reviewers who have experience of the topic in question. As such, we’re always on the look out for enthusiastic volunteers with an eye for detail – could this be you?
The Benefits of Becoming a Reviewer
If you decide to become a reviewer, what’s in it for you? The main benefit is you’ll receive credit for your efforts on each article you review. It might not sound like much, but your name and a link back to your website or social media profile will be seen by thousands of readers.
Being a reviewer is also a great stepping stone towards becoming an author yourself – you become familiar with the process, the other reviewers, and develop your ability to understand what makes a good article.
What Makes a Good Review?
So what exactly does doing a review involve, and what kind of feedback are we looking for? I’ll start by saying that we’re not expecting you to be editors – that’s our job! Spelling and grammar issues, for example, will be picked up when we edit the article, so don’t worry if English is not your first language. A useful review focuses on the technical content of the piece: both with the code, and the prose (text).
When reviewing the code, there are several key things to look at. First, are there any basic technical issues with the code? Things like typos in variable or method names, missing import statements, or logic errors? You don’t need to be an expert in the framework or library being used to catch these sorts of issues.
Tutorials are often accompanied by CodePen demos or GitHub repos with the finished code. Do the demos work as expected in your browser? In the case of code repos, has the author provided enough instruction on how to run the code? Does the install run OK on your machine? These steps can help us weed out cross-platform issues that might cause trouble for readers with a different OS, for example.
As mentioned before, the idea here is not to give a literary critique. The most useful thing you can do is put on your reader’s hat and ask, ‘Can I follow along with this?’. Authors sometimes fall prey to the ‘Curse of Knowledge’. When this happens, they assume the reader has the same background knowledge as they do and can miss out important details that seem obvious to them. Point out areas where further or clearer explanation might be needed.
Along the same lines, does the text lead you through the necessary steps or concepts in a logical sequence, or does it skip steps and jump between unrelated topics? Just a comment asking the author for clarification can help them to understand the reader’s perspective and improve the structure of the piece.
Are technical terms being used correctly? In any technical field such as software development, there are a lot of specialist terms to describe different concepts, techniques and software patterns. It’s helpful to point out if any terms are being used in a non-standard way that might cause readers confusion. On the flip side of the coin, don’t be afraid to mention if you think uncommon (but technically correct) jargon might be too niche and better replaced with a plain English explanation.
Become a Reviewer
If you have any questions about peer review or any suggestions to help us make it better, you can email us at the above address or comment below!