Unless this is the first JavaScript channel article that you’ve read, you’ve probably already noticed the small paragraph that appears in most of our articles (at the top, until recently) which starts “This article was peer reviewed by …”. I’d like to take a look at what SitePoint’s peer review program actually is, why it’s important, and how you can get involved.
What is Peer Review?
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.
Lastly (and not to be underestimated), you are helping to provide good quality, free resources for others looking to level up their JavaScript skills. It’s a great way to give something back and get involved with the community of passionate authors, creators, and developers that hang out on SitePoint.
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).
The code
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.
What about good practices? Does the code follow the idiomatic ways of doing certain things with JavaScript, or with the framework that’s being used? SitePoint endeavors to be a high-quality resource for JavaScript articles and tutorials, so it’s important that the content we publish isn’t inadvertently encouraging bad coding practices. It’s worth bearing in mind that some issues are the stylistic choices of the author; it’s not productive to enter into debates on whether or not to use semicolons!
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.
The prose
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
Hopefully, I’ve given you a bit of an insight into our peer review process and maybe sparked your interest. If you’d like to help review submissions for us all you need to do is contact us at javascript@sitepoint.com and tell us about your programming interests. This could include the frameworks and libraries that you’re familiar with or practices such as unit testing and TDD that you have experience with. This will help us to match you up with articles that align with your interests where possible.
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!
Nilson JacquesNilson is a full-stack web developer who has been working with computers and the web for over a decade. A former hardware technician, and network administrator. Nilson is now currently co-founder and developer of a company developing web applications for the construction industry. You can also find Nilson on the SitePoint Forums as a mentor.
