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

 

  1. Admin assigns article to reviewer via email
  2. Reviewer gives comment on the article page
    • Open the chatroom by clicking on this icon:
  3. Author is notified for every new comment
  4. Author improves article and adds a comment when ready for next review
  5. Iterate steps 2-4
  6. 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

Made with Slides.com