Action(edit)

The Document Review process covers: [#DocReviewPurpose Purpose], [#DocReviewResponsible Responsible], [#DocReviewMethod Method] ([#DocReviewPlanning Planning], [#DocReviewReviewSession Review Session], [#DocReviewFollowUp Follow-Up]), [#DocReviewTime Time], [#DocReviewInput Input], [#DocReviewOutput Output]

Anchor(DocReviewPurpose) PurposeBR We use document reviews to improve correctness of documentation.

Anchor(DocReviewResponsible) ResponsibleBR This can either be

• [:Process Role/Task_Holder:Task Holder] of implementation task doing or correcting document or script. Tasks are specified in the [:Development#CurrentIterationTaskOverview:current iteration task overview].

• [:Process Role/Module Owner:Module Owner] for Documentation module for small corrections.

Anchor(DocReviewMethod) MethodBR 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.

Anchor(DocReviewPlanning) Planning

1. Review participants are specified in the current [:Development#CurrentIterationTaskOverview: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 [:Development#CurrentReviews: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 [:Iteration36:Iteration 36]. 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. <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 NetarchiveSuiteDeveloperManualReview for review of the [Developer Manual]

      4. Copy the text from the template in edit mode
      5. Insert the template it into the new review page and adjust it
   2. "Version": The SVN, CVS or date for revision of document/script to be reviewed.
   3. "Parts/lines": Specifies the parts of the document/script to review (if less that the whole file).
   4. "Task": The assignment or tracker issue that the code has been updated for, e.g. Bug 1512.
   5. "Author(s)": The person(s) who have made changes or additions to the code. Only Initials are given, e.g. ELZI.

   6. "Reviewer(s)": The person(s) who have not been involved in changes, who will participate in the review. If the task is in the [:Development#CurrentIterationTaskOverview:Iteration task list] the reviewer is suggested with the task.

3. The participants agree on a time to review, this date is noted under "Review date" on the document review entry on the [:Development#CurrentReviews: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, or entered during the review as described below.

Anchor(DocReviewReviewSession) Review Session BR 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. Use SET UP REVIEW to go through the review
   1. Discuss each comment in order of appearance.
   2. Those items that the participants don't agree to discard are marked WITH ...

   3. ...Time use (Coding,Documentation,Review) BR <IinitialsOf1Reviewer>: <NoOfManDaysUsed> BR <IinitialsOf2Reviewer>: <NoOfManDaysUsed> BR Remember to set selection of rank in the "Select rank" drop-down list to "Time Used". This is used for the [Iteration review] made in the end of the iteration.

3. Agree to who is doing follow-up in case flaws are found during code review. Usually, this will be the implementor.
4. Update the table in the current [Review Table] with ...

   • Review date

   • Issues found ...

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

# "Follow-up": The person who will do the follow-up on the review specified under 'Issues found'. "Done": whether the review follow-up has been done. Has value "-" if new, "OK" if all follow-ups are done, "OK-wp" (with postpones) if follow-ups are done with exceptions that have been postponed.

Anchor(DocReviewFollowUp) 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 [link Code Review Class Page paragraph].
2. The follow-up person mark the file as fully reviewed on the [link review page] 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.

Anchor(DocReviewReviewPages) Review Pages (technical information) There are two kinds of review pages:

• Document Review Page per Document
• that contains all reviews made on the document
• Document Review Overview per Iteration
• that contains an overview of document (and code) reviews made within an iteration

Name of Document Review page: <Unique name for document> + "Review" Where each part of the name starts by upper case and continuous in lower case (as WikiWords), for example

• UserManualReview

Anchor(TablesFilledPageReview) The below tables (from [:CodeReviewCodePageTemplate:template]) keeps the information for each review of a document (or parts of one). If a document is reviewed more than once, new sections like this get added at the top of the same page. Storing the old reviews with task, date, version and lines/sections has proven useful for tracking down problematic changes.

Anchor(CreationDocReviewCodePage)

• Create new page named as described above based on template ReviewDocumentPageTemplate

• Copy the text from the template in edit mode
• Insert the template it into the new review page and adjust it

If an old review page exists on another media/wiki then this link should be referenced.

Anchor(UpdateDocReviewPage)

Update of Existing Document Review Page

• If the Code Review Class Page already exists then the tables for a new review is inserted in the top of the page in order always to see newest review text first.
• The page may contain a link to old review pages which is placed on another media and therefore not readable for all.

Anchor(DocReviewOverview) Document Review Overview per Iteration The contents can be seen as guidence of what informaiton should be through the review Each iteration has its own page with an overview of code and document reviews, author of changes and who the reviewer is. ...

Anchor(TableFilledReviewsOverview)

• Create new page named as described above

• Copy the text from the template in edit mode
• Insert the template it into the new review page and adjust it

Anchor(UpdateCodeReviewOverviewPage)

Update of Existing Iteration Code Review Overview Page

Anchor(DocReviewTime) TimeBR The input must be review as soon after actual update or creation of documentation as possible.

Anchor(DocReviewInput)

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

Anchor(CodeReviewOutput) OutputBR Reviewed and followed-up input, ready for release test or release.

Anchor(CodeReviewBackground) Background for Document Review processBR The document review process is inspired by the [:Process/Code_Review:code review] process.