Faq

From an Authors perspective
When is my document ready for review?

There are two guidelines to consider. The first are the (project) agreements that are made. For example: version number is correct, the document is saved on a specific location, the template is used and the document is written in the the agreed language.

The second guidelines to consider are more of the ‘social’ kind. For example: the glossary is updated, the text written for the correct audience, unused template chapters are explicitly marked as such, changes are marked with a color in case of an updated document etc.

You must feel confident that the document is, within the agreed boundaries, 100% fit for review. After all, the review is meant to fix defects, not to let the reviewers finish your document!

Permalink.

What can I do when I can not finish my document?

If within the project it’s decided that unfinished documents still must be reviewed “as is”, then the author must clearly mark the spots of which the author is aware that information is missing.

Use “not applicable”, “not available”, “to be filled on <date>” or “to be decided by <name>”. This is more clear to the reader than “N/A” (what does this abbreviation mean?) or “intentionally left empty” (unclear to the reader what this intention might be).

Permalink.

I do not agree with the Importance of a comment

The importance of a comment should not have any impact in the rework that is done. Starting point is that all comments will be handled seriously and rework will be done in case the comment is accepted.

If  the author does not agree with the Importance marked by the reviewer, it’s suggested that the author contacts the reviewer to discuss this. There can be various reasons for this difference in insight. One of these can be that the author does not fully understand the value the document has for the reviewer. This is a good moment to straighten that out!

In all cases: do not argue too much about the importance. It’s the product quality that counts!

Permalink.

Accept or reject comments

In the rework phase the author updates the document based on the provided review comments. A comment can be accepted, rejected or open. The first two states are end states, the status open can be used to mark comments that need discussion. After the discussion the status must be changes to accepted or rejected.

Open

If a comment is not clear, if it needs discussion or if it can not be reworked at the moment (e.g. because of missing information), this temporary status can be used. If the review is finished with issues on status open, this issue must be logged on a to do-list (or equivalent) to be tracked. In case of unclearity, contact the reviewer who noted the comment. Initials and name are mentioned in the review form.

Accepted

If a comment leads to rework, the status accepted is the correct one. Note in the remarks, in short, what has been changed. Just “Updated” or “Reworked” is not clear enough. Respect your reviewers and make whole sentences, eg. “Added paragraph 5.1.3”.

Rejected

A comment can be rejected if the comment did not lead to rework. The author must clearly note the reason for the rejection. Just “I disagree” is not clear enough. Respect your reviewers and make whole sentences, eg. “See [ref1], paragraph 13.4 for the current settings.”

Permalink.