Difference between revisions of "Documentation Validation"

Revision as of 12:43, 23 March 2011

This page provides information about the procedure that must be followed for the validation of the documentation content and the status of this procedure . This procedure is essential for maintaining high quality documentation in the Administrator's[1], the Developer's[2] and the User's[3] guide. The actors in the procedure are the authors of each section in the aforementioned guides, and the reviewers, which are recipients of the information provided in the content for which they are responsible.

Validation Procedure

Each review process workflow consists of three stages

1. The assigned reviewer of a section must classify this section into APPROVED - MINOR CHANGES - MAJOR CHANGES, and set one of these three options into the Content Status column. This classification will give an overall estimation for the situation of the given section and will help each author understand how extensive the changes in his content should be. Reviewers should also provide more detailed comments to authors, in order to inform them about parts that have not clear meaning or must be described in more detail, parts that should be extended to broaden their scope and include more information and missing parts. During this first stage of the review process, the Initial Comments column of the Review Process Status field has yellow color (in progress). This stage finishes when the reviewer opens a ticket(Type: defect, Category (Defect): Documentation) to the author(or the responsible for the corresponding subsystem if the section is written by more than one authors), to provide him with the detailed comments of his review, and places the link for this ticket in the Related Ticket column. The reviewer changes the Initial Comments column of the Review Process Status field to green (accomplished) and the Address Comments column to yellow (in progress).
2. The author/authors of a specific section must perform the changes needed to address the initial comments of the reviewer. When this stage is completed the author changes the Address Comments column of the Review Process Status field to green (accomplished) and the Approval column to yellow (in progress).
3. The reviewer of a specific section must check that the changes performed by the author, addressed his comments. Additional comments can be provided to the author by the reviewer, through the open ticket, in order to help the author address the initial comments. When this stage is completed the reviewer must change the Approval column of the Review Process Status field to green (accomplished), place APPROVED into the Content Status column and close the open ticket.

A new review for a specific section is indicated by inserting a new line, in one of the tables below, beneath the lines that correspond to previous reviews for this section. The reason for a new review can be:

• An extended change in the contents of a section(if this change involves only a specific subsection of this section then the name of this subsection is placed into the SubSection column). In this case the new line should be inserted by the author of the section, who is also responsible for informing the corresponding reviewer about the initiation of a new review procedure for this section. The Due Date in this case must defined as five weeks after the current date.
• A major release closure. In this case the responsible for initiating the procedure is the Documentation Editor.
• Some other reason that demands validation of some parts in the three guides.

The reason must be placed into the Reason to review column. The Due Date depends on the reason for which the review is performed, and the Initial Comments should be provided to the author by the reviewer, at least 3 weeks before the Due Date. If a review process fails to be completed within the Due Date, the reviewer must place the red color (expired) to the appropriate stage in the Review Process Status field. The reviewer can change the Content Status column during the third stage of a review process(i.e. he may decide that a section that needed MAJOR CHANGES, still needs some minor changes after the second stage). If the reviewer considers a section as APPROVED after the first stage, then this review process for this section, is considered to be completed without any actions taken by the author.

Status of Validation

Developer's Guide

User's Guide

Administrator's Guide