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. 


Section

Item

Check

Front Matter/
Overview

Conforms to agreed standard documentation type/title.

  •  

The purpose of the document is clear and complete.

  •  

All known audiences/customers/users are described thoroughly and accurately.

  •  

The scope of the document is accurate and complete.

  •  

Product version numbers and release dates are accurate.

  •  

The table of contents reflects correct page numbers and section names.

  •  

Procedure/

Body Text

All steps in the procedure are accurate and complete. (For short procedures.)

  •  

-or- Step 1 text and screen shots are accurate and complete. (For lengthier procedures and corresponding screen shots.)

  •  

-or- Section 1.1 text is accurate and complete. (For sections of body text that are not broken into steps.)

  •  

All corresponding screen shots accurately display the current version of the software/clearly relate to the step text.

  •  

All charts, graphs, and diagrams are labeled accurately and consistently.

  •  

All safety, privacy, and/or other details are specified.

  •  

Copy Review

Industry and ONAP terminology used consistently throughout the document (e.g., proper nouns capitalized).

  •  

Acronyms are spelled out completely in the first instance.

  •  

All hyperlinks have been tested and work.

  •  

The document flow and structure logical for the audience to follow.

  •  

Spelling and grammar check are complete.

  •  

The document text is concise and clear.

  •  

Standards and Style Review

Follows template structure.

  •  

Headings match standard font, color, size styles.

  •  

Body text matches standard font, color, size styles.

  •  

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.

  • No labels