How to review an article
In this article I will give you some tips on reviewing articles for others, along with thoughts on what you should be looking out for.
Note: There are different terms you'll come across that describe the activities we are talking about in this article. You'll hear:
- development editing — this tends to refer to doing high level work on the article — working on chapter structuring, scope and audience level.
- technical editing and technical reviewing — this refers to editing/reviewing material based on its technical content. Is what the material saying useful, accurate, and appropriate to the audience level? How could it be improved?
- copy editing — a copy edit tends to be a non-technical edit, where the editor just edits the work to improve grammar/spelling. If something looks wrong but the editor is not sure how it should be corrected, they tend to leave a comment for the author to answer.
- proof reading — a proof read is a final check to try to weed out as many last minute typos and other errors as possible. The scope of the corrections really shouldn't be any more major than that at this stage
Generally, when reviewing someone else's article you should first agree on the scope of the review:
- Are you editing the article, or have you been asked just to give comments?
- Are you commenting on the technical content, the article structure/high level content, the spelling/grammar, or all of them?
There should be a bit of leeway, but you shouldn't stray too far from what was originally agreed. For example, if you are just commenting, then you shouldn't make loads of changes. A typo or two would be ok, but for significant changes, put it in comments to ask what the author thinks.
If you are doing a technical edit, then by all means update code samples and wording that you think is inaccurate or wrong, but don't obsess over spelling and grammar, otherwise you might take too long to get the task done.
Of course, if the editor has published a first draft on the Wiki and asked for help with improvements, then anyone should feel comfortable in making changes that they consider valuable. This is the Wiki way, and we need to be comfortable with that.
If something really bad happens to the content, then we can always roll back an edit, but this is obviously something we want to avoid if possible.
When editing content intended for the Wiki, you should make sure it is put on the Wiki in the first place before you start editing it. If it isn't, ask the author to do so, before you start editing. You'll need to login of course before you can then do your edits, but having it on the Wiki first is a good idea because you can then take advantage of the Wiki's version control features, plus the article is then available ad backed up on the cloud. No need for messing around with sending different file versions to each other.
If for some reason you do need to edit some content NOT on the Wiki, make sure it is done in a plain text file. Don't mess around with graphical document editors such as Word or Pages, unless you have a really good reason to do so (for example a visually impaired person might use such an application to write an article because they find the text easier to read in a certain font, zoomed in, etc.)
When you are commenting, it is often a good idea to put comments on the article's discussion page — see the discussion tab at the top of the page. This saves you from cluttering up the article with comments, which can confuse things. Of course, it does mean that the comments won't be in context, so you'll need to describe what part of the article each comment refers to. For example:
"In the first paragraph below the Tips and Tricks heading, you should improve..."
If you are finding it really hard to make a comment understandable out of context, then as a last resort, you can put it inside the article, but to make it easy to find, include a unique flag for people to search for, that won't appear normally in text. For example:
"|| In the first paragraph below the Tips and Tricks heading, you should improve..." or "CHRIS - In the first paragraph below the Tips and Tricks heading, you should improve..."
You should make your edits or comments without fear of breaking anything - the edits can be rolled back if there is a problem. However, make sure that you are confident what you are doing is correct before making changes. If you are really not sure, then you should probably leave a comment instead, asking the author if they think the change should be made.
Different types of review
Let's now have a look at the different types of tech review. These are not always the task of three separate people — it is entirely possible for a single person to act in all three capacities if you wish.
As indicated before, this is a review involved with helping to improve the technical content of the article.
Things to look out for:
- Facts and descriptions that are inaccurate or wrong
- Inconsistent code style
- Code that breaks recognised best practices (for example only using a single vendor prefix on your CSS properties, missing alt text on HTML images, no labels on form elements)
- Code that doesn't work cross browser
- Code that works, but is really slow/inefficient and could be improved upon
- Code that needs more explanation to be understandable
- The other end of the scale — including too much waffle and baby steps when the reader is past that stage already
Anything that you feel should be added/expanded on
- Explanation that is poorly written and therefore doesn't do its job
- Typos in the code
This is more concerned with making higher level changes - to the structure or scope of the article. Instead of making micro-changes to small details, you should be more concerned with moving section around, and suggesting section additions or changes.
Things to look out for:
- Places where the article deviates from the original description or scope. This is not always a bad thing, but you should at least flag it up.
- Places where the order of sections or flow of content seems illogical or wrong, and could be improved
- Places where the article appears to have chunks missing, or superfluous content.
This refers to a copy edit or proof read. Here you are not concerned with the code/meaning; purely with the actual language, meaning the spelling, grammar and style.
Things to look out for:
- Spelling/typos in the explanation
- Bad grammar
- Incorrect word usage
- Really long, run-on sentences that really should be broken up
- Inconsistencies in style of terminology, for example saying "Next I'll do this" in one place and "Next we'll do this" somewhere else, or saying "Multi-col" in one place and "Multicol" in other places. We already have a style guide, but it needs adding to.
- Explanation that just doesn't makes sense, and needs rewriting or making clearer
- Really waffly text that takes ages to make a point. Text should be clear and concise wherever possible.