This FAQ is to help explain the creation and use of Review Documents in a Plato web.

What are Review Documents for ?

A Review Document allows the author to upload an HTML file. Links are automatically inserted at regular tag points in the text where the reviewer may add a comment. As each comment is made it is included in-line in the text.

What is a tag point ?

A tag point is automatically generated at the start of each paragraph and within each cell of a table of the HTML file. They are numbered sequentially and each forms a link to enable a comment to be recorded at that point.

Do the tag points appear throughout the document ?

Tag points are created throughout the document by default, but it is possible to temporarily suppress them by editing the file and adding an HTML comment
<!-- platostop -->
and they can then be restarted using
<!-- platostart -->
Pairs of comments can be used as many times as required. A typical use would be to suppress tag points in text for which comments are not applicable or to generate tags only on a section of text for which comments are being requested.

How do I define a Review Document ?

A Review Document is defined in a similar way to other items, such as a document. It can have a title, version, description and have up to 6 attached files. There are two user-definable qualifications - category and status. You can also define its visibility. Finally, the review has a mandatory start and end dates.

Why might I need more than one attachment?

The first attachment is the HTML file. If the HTML references a gif or stylesheet which is not referenced absolutely, this may be uploaded to the same location. Similarly, if a frameset comprised less than 6 files these could be loaded together. All HTML files are processed to generate tag points.

What is the category?

The category is a means for grouping classes of Review Documents. You may define new categories.

What is the status?

The status is the usual description of the stage of the Review Document, for example first draft, final draft, published. You may define new status values.

What is the visibility?

See the general FAQ on visibility.

What is the version?

The version is the usual identification of the change history of the Review Document.

Is the version mandatory?

No, but it is recommended and must be supplied to be able to created linked versions of a Review Document.

What are linked versions of a Review Document?

It is encouraged that versions of a Review Document are created by making a new version of an existing Review Document (use the Version link) , rather than adding a new Review Document (Add). The difference is that by default only the latest version is seen on the summary page, but with an indication "(+ implies others)" that there are earlier versions. This allows more Review Documents to be seen on the summary page. Different versions retain the same title and category throughout their lifetme, but their status and visibility can change.

What appears on the home page ?

As usual, a maintainer can configure the number of Review Documents to appear on the home page. The section contains the titles of the latest Review Documents, sorted by start date, together with the review start and end dates and links to the first attached HTML file and to a table of comments..

What appears on the summary page ?

By default, all Review Documents are displayed but only the latest version of those with linked versions (see above). Review Documents can be subsetted by category or age, grouped by category or all versions can be shown. Sorting is by default by creation date, but the column headings are links that allow the data to be sorted on different fields. Each entry shows the number of comments to date, with a link to view the table of comments.

What does the table of comments show me?

For each comment the user identification, severity (critical,major/minor), nature (editorial/technical), title,rationale and the text of the comment are given. A link takes the user directly to the comment within the HTML file.

What are archived Review Documents ?

Review Documents can be archived, rather than deleted. An indication is given on the summary page if any archived Review Documents exist and the summary can be switched to display them. Review Documents can be unarchived at a later date.

Why are the updated facilities restricted ?

It is not possible to upload new files after a Review Document has been created, because there is a risk that existing comments would become misplaced if the tag points were numbered differently. Instead, a new version of this document should be created.

What happens when the review end date is reached ?

The document becomes read-only: no further comments can be added nor existing ones changed or deleted (except by maintainers).

Can I have a public level Review Document ?

Creating a comment is possible only if the user can be identified and authenticated, which means that they need to be accessing a protected level. For this reason public level Review Documents cannot be created.

Are there variations in the styles of comments that can be required ?

A review document can be defined as one of three comment styles:

Informal comments	The input form will just require the text of the comment
Formal Review	The comment will also require a title and rationale
Company Review	The comment will also require a company identifier

What is the alert checkbox for?

Most items allow the creator/updater to send a preset e-mail alert to the list appropriate to the visibility level. It contains identification of the creator/updater and a URL to view the item.

What is the alert email field for?

It is possible to supply an email address to which an e-mail alert will be sent each time a comment is added or updated.

Comment Guidance

• Critical = show stopper, we'll vote against publishing the document unless this is changed the way we want it
• Major = a serious problem that must be fixed; we are proposing a solution but are ready to compromise
• Minor = a nuisance, we won't fuss if it is not fixed our way

Nature:

• Technical - when changing anything in the technical content.
• Editorial - changing only text without changing content. Can be applied by the editors without discussion.

Rationale:

• Reason that change is needed, reason that suggested change is preferred over other possibilities, etc. This is your chance to persuade other companies to support the change request.

Changes

• Please include unambiguous identification of precise text or illustration, where the change is needed, quoting text where required.

  Please provide explicit instructions using keywords to make the change unamb iguous, i.e. add, create, change, delete, move, merge, rename, replace, restore , update, for example:
  Change from: existing text To: new proposal , or Insert words before existing text, or Delete the second sentence.

  There may be cases where you feel unable to provide text, for example where a clarification is requested. In such cases you have two options:

  • write down one of the possible alternatives; this at least serves to illustrate your concern.
  • contact someone else, in advance, who may be able to suggest some wording, before submitting your Change Request.

Further information on Plato including troubleshooting tips is available here