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

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 [Iteration task list]. Usually it is the implementor and another developer.
  2. The implementor specifies the document (parts) to be reviewed

Create new review

  1. Select a proper titel. If it corresponds to a task in the current [Iteration task list], it should have the same title, as is written there.
  2. Set yourself both as .......'moderator', and 'author' (unless code is authored by somebody else).
  3. Write relevant comments in the ........"Statement of Objects" for instance genral comments to the review and list of deleted file or class names that for obvious reasons cannot be included.
  4. Add LINKS the files included in the review.
  5. Add a .....revision comment to each of the files with specific lines to be review
  6. You notify the reviewer ...
  1. Make an entry with review information for the review in the wiki current ...[Review Table] (see for example ????) ....
  2. The participants agree on a time to review.
  3. Before the review time, each participant reads the document thoroughly and note problems - big or small - that should be discussed.

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.

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:

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

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)

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

Anchor(UpdateDocReviewPage)

Update of Existing Document Review Page

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)

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.