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.
- 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 and editibility. 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
- What is the visibility?
- See the general FAQ on visibility.
- What is the editibility?
- Whereas the visibility defines what levels can see the document, the
editibility defines what levels can add comments. So it is possible to
make comments added by a lower level visible to a higher level without those viewers
being able to add their own comments
- What is the version?
- The version is the usual identification of the change history of the
- 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 lifetime, but their status and visibility
- 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
- 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 un-archived 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.
- 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 defines as one of three comment styles:
||The input form will just require the text of the comment
||The comment will also require a title and rationale
||The comment will also require a company identifier
Chris French - 13 Oct 2006