Guidelines for Reviewers
Devopedia Web App Intro
Rewards Program - Process
Reviewer does this
The Review Process
- Create account or use existing account
- Use same email as in recent communication
- Admin assigns article to reviewer via email
- Reviewer gives comment on the article page
- Open the chatroom by clicking on this icon:
- Author is notified for every new comment
- Author improves article and adds a comment when ready for next review
- Iterate steps 2-4
- Reviewer notifies webadmin@devopedia.org when article is ready for publishing
Review Comments
-
Comments are truncated to 5000 characters
- For long comments, split them manually into multiple comments
- Number your review points for easy cross-referencing or later discussions with author
- Optional:
- Select the particular version you are reviewing: usually this is the latest version at the time of review
- Select the particular section you are commenting on
- You can edit your own comments: authors and other commenters will be notified
- Comments are public: don't share sensitive information
Core Content Guidelines
Adopted from Wikipedia
Who's the Audience?
Data Science
Project Manager
Developer
Lay Person
REST API to GraphQL Migration
Python Data Types
Qualities of a Good Reviewer
Reviewers should not assume that they know the topic very well. They should investigate facts before commenting.
Humble
A good article has to get many things right. A reviewer has to look at the big picture and also the fine details.
Meticulous
For example, a reviewer working with company X should not be biased when reviewing an article related to a product of X.
Impartial
Reviewers shouldn't be too harsh on authors. Give comments in a neutral tone. Compliment authors when they get something right.
Polite
Some authors may not understand the review comments and may require further clarification.
Patient
Minimum Requirements
to be considered for a review
1200 words
No warnings
Good references
Reviewers may at their discretion commence a review
even when the above are not met.
Article Warnings
Client-side and server-side
- Maximum word limits
- Summary: 150
- Discussion
- 2000 total
- 200 per Q&A
- Milestones
- 100 per milestone
- Minimum word limits
- 500 to remove warning
- 1200 to publish & pay
- Other limits
- 3+ images/videos/audio
- 3+ Q&A in Discussion
- 3-15 milestones
- 3-8 tags
- 3-6 See Also items
- 3-6 Further Reading items
- 1.5+ references / 200 words
- 1.5+ citations / 100 words
- Warnings when some sub-standard references are used
Research Sources
Primary Sources
Secondary Sources
- Research papers (IEEE, ACM, Elsevier, arxiv, etc.)
- Books
- Official docs, videos or tutorials
- Historical records (emails on mailing lists, etc.)
- Standards
- Press releases
- Tech blogs
- Wikipedia
- News articles
- Tutorials, videos, etc.
Sources: Good and Bad
Don't prefer those with few claps, likes, shares, views, etc.
-
Quora or StackOverflow answers
-
Medium, Dev.to or HackerNoon articles
-
YouTube videos
Examples of good sources
-
Official sites of tech companies: Intel, NVDIA, RedHat, IBM, Google, MongoDB, etc.
-
BBC, CNN, Washington Post, The Guardian, etc.
-
WIRED, The Next Web, ZDNet, CNET, DZone, Android Authority, Computer World, Forbes, etc.
-
Coursera, Khan Academy, lecture notes, etc.
-
Conference proceedings/recordings
Some sources are perceived as low quality
-
data-flair.training, educba.com, edureka.co, geekflare.com, geeksforgeeks.org, guru99.com, javatpoint.com, journaldev.com, simplesnippets.tech, simplilearn.com, techvidvan.com, tutorialspoint.com, w3schools.com
Some acceptable sources
-
Wikipedia, Analytics Vidhya, vendor blogs, etc.
Reference Example
Adapted from Chicago Manual of Style (Author-Date system)
http://www.chicagomanualofstyle.org/tools_citationguide/citation-guide-2.html
What to Review
Main
Others
Tags
References
Further Reading
Summary
Discussion
Milestones
Aspects of a Review
Content
Style
- No factual errors
- No obvious omissions in subject matter
- Content is relevant and properly scoped
- Content is organized in a logical manner
- Text complements embedded media
- Good sources are used as references
- Citations are accurate
- Writing style follows author guidelines
- Content is written for a beginner
- No grammar or spelling errors
- Good use but not overuse of styling
- References and citations are formatted correctly
Tips for Reviewers
Good images & videos
Plain English
Short sentences
Concrete examples
Facts not opinions
Good
sources
Explained, not just defined
Not just copied
Technically precise
Common Problems
Authors use only Google Search and not Google Scholar. Their sources are ad-driven sites, blogs and Wikipedia.
Poor Research
Authors attempt to game the system by including arbitrary citations or images to remove warnings.
Gaming
Authors don't summarize from multiple sources. They copy and paste from one or two sources, substituting words.
Plagiarism
Content is repeated across the article. Content is poorly organized. Disconnected paragraphs: ideas don't flow.
Repetition
References formatting is improper. Content has sub-headings, which is not preferred.
Formatting
Self-Study
Study review comments in already published articles:
Conclusion
- If this initiative is successful, we'll introduce more automation and greater promotion of the Reviewers' Network
- Reviewers are not paid for their service right now but Devopedia trustees will look into this later this year
- Reviewers can also be volunteer authors but they can't be paid under the Rewards Program
- Author and reviewer email addresses are kept private: they can communicate only via the chatroom
A big thank you to reviewers
for your expertise and time
Guidelines for Reviewers
By Arvind Padmanabhan
