Review etiquette

This guide aims to clarify expectations between reviewers and authors. This etiquette can be applied universally, with the underlying principle that comments are actionable unless they specify otherwise.

Who is involved in the review process and in what capacity?

Each report should have a designated author who is responsible for responding to each stage of the review process. If a project has more than one author, one should be identified as the lead writer, and they are responsible for addressing the reviewers’ comments. The author can tag others involved in the design and development of the report to address specific questions. In these cases, however, the author is still ultimately responsible for making sure those queries are answered.

Reviewers include, but are not limited to, the following roles:

• Analysis manager for outline reviews.

• Research analysts for stat checks.

• Associate analysis coordinator for visuals review.

• Editors for draft development, editorial review, and proofreading.

• Heads of Analysis and External Affairs for final reviews and approvals.

What are the common expectations for reviewers and authors? 

Suggestion Mode: Both the reviewer and the author should always use Suggestion Mode when making any changes to the document. This helps the reviewer keep track of changes and ensure consistency.

Communication through Asana: Once the reviewer has completed their review, they will tag the author in Asana. Likewise, once the author has addressed all comments in the document, the author should tag the reviewer in Asana. The reviewer will tag the next reviewer once the piece is ready for the next step of the process.

Responding to comments: When the author responds to a reviewer's comment, they should not resolve the comment — the reviewer will do this once they feel their query has been fully addressed. Similarly, reviewers should not resolve comments from other reviewers. Everyone working in a document should assume the comment is not addressed if it is not resolved.

*Remember: Do not reject suggestions or comments. The author should not “reject” a reviewer’s suggestion; If they disagree with the change, they should leave a comment explaining why. The reviewer should do the same.

Adhere to deadlines: Reviewers should ask for the author’s turnaround time at each stage of the review. Authors should adhere to the deadlines on Asana tasks and deadlines agreed between them and the reviewers. 

How should reviewers deliver feedback?

Feedback should be clear and actionable: Avoid reactive comments that are not constructive for the author. The language of the comment should indicate the action that’s necessary to amend. Sometimes this can be a question to consider relative to a data point, piece of evidence, context, or even just in relation to the writing. This sets the expectation that the author will both respond to the question in the comment and suggest a related edit in the text. 

DON’T: This is not useful to the conversation. 

DO:  In its current form it’s not clear to me how this contributes to the conversation. Can you please clarify this part so it’s clear why it’s relevant to the reader at this point in the report? 

DON’T: Is increased fighting in this region related to drug trafficking?

DO:  Is the increased fighting in the region related to drug trafficking? If so, I suggest making that connection a bit clearer for the reader by mentioning that aspect here as well. 

Reviewers should be conscious of the approaching deadline and adjust their feedback accordingly. Please avoid asking for refinements that would require more time than is available, according to the agreed deadline. If an issue is identified at the end of the review processthe best practice is to discuss this as soon as possible with the author so it can be resolved. If it’s preferable, it can also be flagged on Asana.

DON’T: This is interesting, but I wonder if there have also been similar clashes with a group known for transporting illicit fuel. Please add a paragraph on this and reformulate the section to make this a central focus.

DO: (In Asana) @Author Unfortunately there is an issue with the way the data were interpreted and presented, which will require some time to resolve. Please let me know how long you estimate it will take to make these adjustments

If you need to make large edits, always offer an explanation. Large interventions in a text by anyone but the author during any stage of the review process increase the likelihood of introducing errors or disrupting the flow of information. Good editorial practice dictates that changes to more than 50% of a sentence should come alongside a discussion with the author, and a clear explanation for the change. Therefore, reviewers should guide the author on the changes that they suggest by explaining their reasoning and providing potential examples of alternatives in a comment.  

DON’T: (Reviewer applies direct edits to the text in Suggestion Mode that changes the whole sentence without providing an explanation)

DO: So here you say that these two groups are operating very differently, but then the following sentence talks about what they do that is the same. Or is it the case that by "different zones" you mean that they approached expansion with two different launchpad areas? If it's the latter, the use of "both" at the beginning of the sentence is a bit confusing. If it's the former, let's use a transition word like "However" at the beginning of the sentence to make it clearer.

DON’T: This sentence didn’t make sense so I changed it.
DO:  The phrasing here is a bit awkward. Can we say this instead: "...into a support zone. In early 2024, it became a combat zone as the group began launching attacks..."

DON’T: I moved around this paragraph because it works better in the introduction. 

DO:  I think starting the section with this paragraph on the data trend confuses me about the focus of the section. I wonder whether this fits better in the introduction as kind of the premise/impetus for the report. Then, this section can squarely focus on providing the necessary context with the data viz you propose providing the visual anchor. What do you think?

Leave comments on the good along with the bad. This is just an active reminder to vocalize the sentences, paragraphs, or other bits of language that are done well in a draft!

Adhere to the agreed timeline for review. As a remote organization, it’s important to be mindful of our colleagues’ time. This is particularly important when we expect them to undergo several hours of work to respond to our comments. Therefore, before starting their review, reviewers should always:

1. Acknowledge the receipt of the draft when it’s ready for review.

2. Provide a timeline for your review that includes the time zone and is within the deadline assigned on Asana, e.g., “I will get started on this review tomorrow morning, so it should be ready for you by 15.00 CET.”

3. While this shouldn’t be the case, flag if there are any comments or edits that are still pending in the document.

4. Always communicate any possible delays as soon as possible. In cases like this, over-communication is actually a recommended practice. 

5. Be mindful to give the author enough time to address the comments and work through the feedback thoroughly. 

How should authors respond to comments?

During the review stages (outline review, editorial review, final review, etc.) the reviewer will ask questions related to the clarity, accuracy, and readability of the text and analysis. Keep in mind the following principles: 

Assume that the question is guiding the author to add or adjust something in the text: If the editor asks for clarification on the details of an event, instead of copying and pasting the notes from the event as a reply, please try to answer the question by editing the text and/or replying to the comment explaining why a text edit is not possible.

Read through the piece with the suggested edits and comments once before working on them, and when addressing them, do so from top to bottom. Mistakes introduced during the review process can be prevented by following these two guidelines, as it ensures the edits and responses are made in the context of the wider piece. As you read through it the first time, feel free to make notes, but try to not respond until you’ve read through the piece and feedback in its entirety.

Inquiries from a reviewer should trigger the following responses: 

Can you clarify?

If the editor indicates that a sentence is unclear and asks for more information to make it easier to understand or read, make a suggested edit in the text directly where possible instead of offering only an answer in the comment thread. This cuts down on the editor needing to make a change based on the answer and then asking if this change is accurate.

Is this edit OK?

If the editorial reviewer comments asking for confirmation that an edit has not rendered the text inaccurate (e.g., “Is this still accurate?” or “Is this edit OK?”), feel free to resolve the comment if the edit is accurate. Leave the comment open with a reply if the edit was not accurate and please try to offer an alternative edit that might achieve the same end (e.g., breaking up a long sentence into two). 

Stat check

During the stat check, a reviewer will ask questions related to the events used in the dataset. Those inquiries should trigger the following responses: 

What is the event ID?

• Author: Provide the event ID.

• Reviewer: Check the event ID, IF the event matches what the author has written, resolve the comment. IF it contradicts what the author has written, leave another comment explaining the difference.

• Author: Respond and update the text if necessary (leave the comment open).

• Reviewer: acknowledge the comment and resolve.

How did you filter for this data?

• Author: Provide information on how they filtered the data (e.g., manual count, tableau calculated field).

• Reviewer: Check the author's response. IF the filter seems correct, use it to check the data. IF the filter is not relevant / contains errors, leave a comment as to why AND provide a suggested alternative + data figures with the updated filter.

• Reviewer: IF the data matches what the author has written, then resolve. IF the data does not match what the author has written, follow the factual difference process.

When there is a factual difference (e.g., number of fatalities, date of event) and the reviewer responds with what they are seeing in the data and asks about the filtering, the reviewer should also leave an explanation as to how the data was filtered. E.g.,  the report text says "In Libya, there were 10 political violence events in 2024" and the reviewer responds, "I see 30 events. I filtered the data by X, Y, Z.  How did you get your figure?”

• Author: IF you now see the same as the reviewer, update the text and leave a comment. IF you do not, leave a comment saying which number you see. If you have any suggestions as to why the reviewer may be seeing a different figure, also include this in the comment.

• Reviewer: IF the author has updated the text, resolve the comment. IF the author does not see the same figure, work with the author via the comments to determine the accurate figure. IF this cannot be resolved, leave a comment for the senior research analyst.

• Author: Once the final figure has been determined, add it to the text and acknowledge this in the comments.

• Reviewer: Resolve the comment.

Rephrasing suggestion (e.g., percentages should be expressed as xyz, this should be VTC rather than VAC, etc.)

• Author: IF you agree with the suggestion, update the text and resolve the comment. IF there is disagreement, respond to the comment with an explanation.

• Reviewer: IF you agree with the author’s suggestion, acknowledge and resolve the comment. IF there is disagreement, respond to the comment with an explanation.

• IF there is still disagreement, seek the opinion of another reviewer/editor.

• Author: Respond to the second reviewer/editor and resolve the comment once the text has been updated, if necessary.

Visual review

• Research analysts should go through the visuals submission checklist before uploading the visuals.

• Make sure to run a spell and grammar check on any text on the visuals before submission.

• Visuals should look in “final form” ahead of the review process.

• Edits to the visuals should be submitted in Suggestion Mode, so the reviewer is aware that changes have been made. Likewise, after addressing comments from the reviewer, add a comment acknowledging that. 

Who resolves comments and when?

If a comment from the content review is still unresolved by the time the piece is ready for the editors, please reply to it to indicate why the comment is still open before sending it for editorial review. In-line edits by research analysts related to the stat check should be resolved by the author. Always send a clean copy of the document to the next reviewer to ensure the author and reviewer are on the same page and as a courtesy to the next reviewer. 

The person who made the comment is responsible for resolving it within the same review stage. This applies across all stages: draft development, editorial review, and final approval, and across all types of reviewers: research analysts, editors, and final reviewers/approvers.

What comments may still be unresolved when a document is passed to the next stage of review?

Authors should not send a piece to editorial review if it is over the word limit. Exceptionally, if you need help figuring out where to cut down the length, please warn the editorial reviewer and suggest, if possible, where you think cuts might be best. If the extra length has been approved by the content reviewer, please indicate that on the document. 

Always indicate in your Asana pass-over message if there are still pending comments and why. There are a few other types of comments that can remain open in the doc when it moves to the next step: 

• Guidance or inquiries for members of the web team.

• Data pending confirmation.

• A developing fact that may change before publication (e.g., election results, trial outcome, policy decision, etc.).

• Title deliberation (managed and finalized by the lead editor).

Further readings:

• Publications guide 

• Style guide 

• Glossary

• Visual style guide