Purpose

Effective documentation reviews help catch errors not only in documentation, but in the projects themselves. Better projects and supporting material reduce issues/bugs make end-users happier.

To that aim, the committer documentation review checklist should be completed by all ONAP Project SMEs and Documentation Project committers to ensure accuracy, clarity, and consistency within each document.

How to Use this Template

Here are some tips for using this template and completing a documentation review.

NOTE: This checklist relies on having a clear style guide that all developers/writers must follow to maintain consistency and a common look and feel across all ONAP projects.

Customize the Checklist

Not all sample line items in the checklist will apply to each specific document or review need. You can customize the checklist items to your document so you can capture specific feedback and improve the overall communication.

The front matter/overview text could include a purpose statement, document description, target audience, scope, instructions for use, etc.  The body or procedure area could include procedure steps, instruction sets, and other body text in your document.

You can easily add, modify, copy, and remove text as it applies/relates to each document. For example, you may want to add rows to the Procedure/Body Text section to capture reviews of all subsections of a lengthy procedure. 

Prepare the Reviewers

Create a clear message on what you want reviewers to review (then you can avoid the dawdling on unfinished or unformatted sections.)

You can customize this checklist and use it for different purposes. Use this checklist in a technical review to capture changes as a group discusses them. Or, send the checklist to individual reviewers along with a deadline. 

Adapted from https://techwhirl.com/documentation-review-checklist-template/

Once agreed, we could make a Confluence template so that each new piece of documentation could use their own specific checklist.