Creating DocReview^© Installations and Archives:
The Editor's Guide to DocReview

The Editor's Forms

The editor performs the four main functions of the system by using forms. The forms may be accessed through the Managing DocReview Installations page.

The Create Installation form:
This form allows the editor to provide the information necessary to place a document in a DocReview Installation.
The Archiving form:
This form allows the editor to provide the information necessary to place a DocReview Installation into the archives.
The DocReview Deletion form:
This form allows the editor to completely erase all traces of a DocReview. This is usually done to correct errors made in laying out review segments in a new DocReview.
The Comment Deletion form:
This form allows the editor to erase all viewable traces of a comment in a particular DocReview. The offending comments are stored for archiving purposes in a file accessible only by the editor.

Setting Up the Review Segmentation

DocReview does its work by breaking up the base document into short segments, usually paragraphs, that have a limited scope. This segmentation process is done by the editor by selecting types of text elements to be annotatable. The editor can also insert an editor-defined tag such as <FAKE> or <RS> (default)to cause a review segment to be started where the tag was placed in the base document. Review segments usually run from their start to the beginning of the next review segment.

Segmentation Suppression: The <NOTAG> Tag

The blanket specification of review segments by element type will often create segments where you would prefer not to have them. For instance, suppose you have selected paragraphs and you have a short section of dialog that you would like to treat as a single section, like this:

Tim: "What do you think of this tool?"
Alan: "I like it a lot, especially the comment files."
Mary Ann: "You don't get lost in a tree of comments."

Under the normal usage, each of the lines would be tagged as a review segment. To get the entire section under a single review segment, use the <NOTAG> tag to suppress review tags on the second and third lines:

Tim: "What do you think of this tool?"
<NOTAG>Alan: "I like it a lot, especially the comment files."
<NOTAG>Mary Ann: "You don't get lost in a tree of comments."

Almost any time you use <NOTAG> you will need to use <ENDSEG> as well, read on.

Segment Termination Tag: The <ENDSEG> Tag

The document under review may have section headings, tables, or graphics that are formatting, not content. In order to exclude these objects from the review segment, while leaving it in the text, the <ENDSEG> tag is used. <ENDSEG>, ;<SEGEND>, </RS> are all synonymous. Normally a review segment ends at the beginning of the next review segment. By inserting this tag, you can eliminate everything between the tag and the beginning of the next review segment. The user sees the end of the review segment as a ¤ mark.

Almost any time you use <ENDSEG> you will need to use <NOTAG> as well.

The Files Created in the Installation

Every DocReview has its own files stored in a directory named by the "Review Nickname" supplied in the creation form. Let's call it MyReview. When first created, there will be four files in MyReview: the base document basedoc.html, the parameter file parms.txt, the comment log file log.txt, and the comment tracker tracker.txt. As comments come in there will be comment files added. A copy of all comments is stored in the cumulative comment file cummulate.html, and for each review segment that catches comments a review segment file pointnn.html where nn is the review segment number.

basedoc.html
The basedoc contains the text of the document that is being reviewed. This file is a standard HTML file that may have special tags added (<NOTAG> or <rs>). You may edit this file as long as you do not add or delete any segmentation tags. This means that typos or minor grammatical error can be fixed, or minor "fixup" comments may be incorporated. NOTE: Do not confuse this file with the base document you used to create the DocReview. File basedoc.html is created by the DocReview programming and contains numerous special tags that were not in the original base document. The original base document may be saved to facilitate creation of a new version of the document, but an existing DocReview has no need for it.

parms.txt
The parameter file contains 18 lines, each of which stores a particular parameter. Those lines are:

Line 1 is the latest comment line. You may edit this line.
Line 2 is for the "created by" line below the title. This line can be edited.
Line 3 is for the comment write-protection password. You may edit or add a password.
Line 4 is for the comma separated notification list (no spaces!), it can be edited to add or delete notification addresses.
Line 5 is for the base URL of the DocReview directory. Do not edit.
Line 6 is for anonymity of the log file. It must be TRUE or FALSE. It may be edited.
Line 7 is the title line. This text appears in the title of the DocReview Page. Editable.
Line 8 is the sponsor line. The name of the editor, HTML that can be edited to be as fancy as you wish as long as it is one single line.
Line 9 is the color line. Editable if you wish to change the color of the DocReview titles.
Line 10 tells DocReview whether paragraphs were tagged. Don't change this!
Line 11 tells DocReview whether list elements (bullets) were tagged. Don't change this either.
Line 12 tells DocReview whether editor-defined tags (<rs>) are used. Don't change.
Line 13 tells DocReview what editor-defined tags look like. Don't edit!
Line 14 is the general comment enabler (TRUE/FALSE). Don't change.
Line 15 is a placeholder that is not used. Editable, but meaningless.
Line 16 is the special instructions line. Default is blank. Change at will.
Line 17 tells DocReview whether tables are tagged. Don't change.
Line 18 tells DocReview whether all the table cells are tagged. Don't change.

log.txt
The log file contains a line for the creation of the DocReview, a line for every comment, a line for every time the DocReview is read, and when (and if) the DocReview was archived. Each line contains information that is used by the "What's New" feature. Editing this file will interfere with analysis programs used in research regarding the use of DocReview. It is passworded and inaccessable from the WWW.

tracker.txt
The tracker file contains a list of numbers that record the number of comments that each review segment has received. DocReview programming revises this file when comments are added or deleted. Editing this file manually will likely damage the DocReview.
Line 1 is for the cumulative number of comments received.
Line 2 is for the general comments, if they have been requested; if not it will have the tally for the first review point.
Line 3 and subsequent lines tally the nuimber of comments against each review segment.

pointnn.txt
The comment files may be lightly edited (typos and indescretions). Any changes in the comment files must also be made in the cumulative comment file cummulate.html. If a comment must be removed, use the Delete Comment button on the management page.

cummulate.txt
The comments are copied to a cumulative comment file as they are received. This file can be retrieved from the "Special Features" page. It may be edited to correct typos.

The finishing touches

Always check your work. Look at the DocReview you have just created. There may be some little problems that detract from the reviewer's experience. You may find that some W... tags hang up in the spaces between paragraphs. This is caused by having a review tag at the end of a line rather than at the beginning. HTML converters often do this. The W... tags may be in a large, bold or colored font. This is caused by having the review tag preceded by a or tag. Always best to have the review segment tag at the beginning of the line.

There may be some links that do not work. DocReview changes the directory that the base document is in, so relative links do not always work. This is normally no problem since readers are reviewing, not visiting other pages. Should you desire a completely "clean" installation you might change the links in basedoc.html to fully qualified URLS including http:// , the links will then work properly. Be very careful when making changes to basedoc.html; changing the review segment structure will ruin the DocReview.

Announcing the DocReview to your collaborators

Each new DocReview needs to introduced to your collaboration by e-mail. While there is a section in the DocReview header for special instructions, experience has shown that even if the instructions are in bold red, they are seldom read. The message that introduces the new DocReview is a more effective place to provide special instructions.

Especially important is the message that introduces your first DocReview to the collaboration. That message must tell them about the document being reviewed, DocReview and the use of DocReview, see example message.

DocReview Archives

The editor often finds that there is a need to retain the DocReview after its purpose has been served. New editions of documents are prepared, meeting minutes are released, specifications are completed, etc. DocReview has an archiving capability that provides an easy way to set these "spent" reviews.

A DocReview Installation is archived by filling out and submitting a form that pops up when the "Archive a DocReview" button is clicked on the management page. The editor simply fills out the four fields: installation directory nickname, archive directory nickname, a short title, and a descriptive phrase. The installation is archived under the directory "archives/nickname". The installation is removed from the DocReview directory and from the index of DocReviews. The archive program appends the newly archived installation to an index of archives.

The archives are read-only and are read by clicking on the links on the archive index (archiveindex.cgi).

Deleting DocReviews

Frequently, the first try at installing a DocReview produces a badly formatted DocReview. While it is often possible to correct problems by editing the files produced in the installation of the DocReview, it is safer to correct the base document and delete the DocReview and start over. To delete a DocReview go to the "Managing DocReview installations," select "Delete a DocReview," then choose the DocReview to Delete.

Occasionally, a DocReview does not attract any activity or serves its purpose and does not need to be archived. These DocReviews should be deleted. Deleting a DocReview completely destroys every file associated with the DocReview. The DocReview is also removed from the site DocReview index file, activelist.txt. December 12, 2002

Creating DocReview © Installations and Archives:The Editor's Guide to DocReview