edit

The Document Review process covers: Purpose, Responsible, Method (Planning, Review Session, Follow-Up), Time, Input, Output

Purpose
We use document reviews to improve correctness of documentation.

Responsible
This can either be

• Task Holder of implementation task doing or correcting document or script. Tasks are specified in the current iteration task overview.

• Module Owner for Documentation module for small corrections.

Method
A document review consists of 2 or more persons that read the document/script/assignment and in a structured way identify changes that will improve it. Our process for document review contain planning, review session and follow-up as described below.

Planning

1. Review participants are specified in the current Iteration task list. Usually it is the implementor and another developer.

2. The implementor specifies the document (parts) to be reviewed in a new row in the document review table on the current Iteration review overview (the meaning of the different columns are also described in the end of iteration review page):

   1. "Document": Link to issue review page for document named with identification of the document, e.g. http://netarchive.dk/suite/AssignmentDeploy1 - See example in Iteration 36. A new review is inserted in the top of the page in order always to see newest review text first.

   2. If the document review page do not already exist, make a new Document Review page on basis of template ReviewDocumentPageTemplate:

      1. Create new page named according to the document name as follows:

      2. !DocumentReview/<Unique name for document> + "Review"

      3. where each part of the name starts by upper case and continuous in lower case (as WikiWords), for example DocumentReview/NetarchiveSuiteInstallationManualReview for review of the New version of installation manual

      4. Copy the text from the template in edit mode
      5. Insert the template it into the new review page and adjust it
      6. If an old review page exists on another media/wiki then this link should be referenced.

   3. Version: The SVN, CVS or date for revision of document/script to be reviewed.

   4. Parts/lines: Specifies the parts/section/lines of the document/script to review (if less than the whole file).

   5. Task: The assignment or tracker issue that the code has been updated for, e.g. Bug 1512.

   6. `Author(s)": The person(s) who have made changes or additions to the code. Only Initials are given, e.g. ELZI.

   7. ~+`Reviewer(s)": The person(s) who have not been involved in changes, who will participate in the review. If the task is in the Iteration task list the reviewer is suggested with the task in this task list.

3. The participants agree on a time to review, this date is noted under "Review date" on the document review entry on the Iteration review overview page

4. Before the review time, each participant reads the document thoroughly and note problems - big or small - that should be discussed. These can be written into the document review page (e.g. DocumentReview/NetarchiveSuiteDeveloperManualReview), or entered during the review as described below.

Review Session
This part, while central to the whole process, should not be allowed to drag on forever. If the reviewers cannot agree on how to fix a problem within a few minutes, the item should be marked as "consider how to..." rather than prolonging the discussion.

A typical review session should take no more than an hour (and most take less than that). If it takes longer, the review should be stopped and a time to continue should be agreed upon. More than an hour of straight review reduces the efficiency.

1. The participants meet on the phone (only physical meeting if possible)

2. Note ~+Time use (Documentation,Review) in the header, given in number of person days used.

3. Discuss each comment in order of appearance in the document. Those items that the participants don't agree to discard are marked with status "rejected".

4. Fill in severity, and in case thios is "major" or "showstopper" a tracker issue must be reported as well.

5. Agree to who is doing follow-up in case flaws are found during code review. Usually, this will be the implementor.

6. Update the table in the current Iteration review overview in the entry for the actual review:

   • Review date

   • Follow-up - initials of person decided to do the follow-up.

Follow-up

1. The follow-up person goes through the list of items and handles each of them. Depending on how an item is handled, the item is marked under Status on the document review page.

2. The follow-up person mark the file as fully reviewed on the Iteration review overview in the entry for the actual review, once all items have been handled.

3. If the implementor feels the changes are significant enough to require a new review, another review cycle starts. The first review is left as-is. This rarely happens, and should only happen when design issues have been identified and resolved during the review process.

Time
The input must be review as soon after actual update or creation of documentation as possible.

Input
Usually the input is implementing a Tracker Issue for documentation, but it could also be script or an assignment.

Output
Reviewed and followed-up input, ready for release test or release.

Background for Document Review process
The document review process is inspired by the code review process.