Quick Guide Project: documentation review checklist

As you know, today's class will consist of documentation review, for which your assigned tester will read through your documentation (but not actually complete steps until Wednesday's scheduled usability testing session).  Even before documentation review, I would like you to have your assigned tester complete a survey, in which you solicit information that will help you shape your documentation to meet your audiences' needs.

After you and your tester have both completed each other's surveys, you should begin documentation review.  It's important that you not combine documentation review and usability testing, since documentation review can yield valuable feedback that will help you revise your documentation into a better-quality product that's more suitable for usability testing.

The following "check-list" of items is meant to help testers focus their energies during documentation review on certain key characteristics of successful software documentation. You'll probably recognize a number of these from what we've covered so far. You're not required to turn in a completed check-list -- but I would like you to incorporate it into the feedback that you give the writer regarding his or her documentation.

Keep in mind that you also need to consider additional program/task-specific considerations. I've identified the following items because they're crucial to any kind of software documentation -- and, of course, reflect what we've covered so far:

Product/task research

• Does the documentation present a basic knowledge of the program and/or the task presented?
• Does the documentation appear to accurately and ethically present information regarding the program and/or task?
• Does the documentation present information about projects to which the user can apply the task that he or she is completing?
• If applicable, does the documentation effectively present and/or
  explain differences between a newly-updated software program and
  previous versions of that program?
• If applicable -- and if known -- does the documentation attempt to address limitations of already-existing documentation?

Audience analysis

• Does the documentation specifically or implicitly refer to a target audience?
• Does the documentation reflect an accurate and realistic assessment of its target audience?
• Does the documentation acknowledge this target audience throughout
  the document, and/or within multiple documentation components
  (examples: introduction and written steps, or introduction and sample
  project, or introduction and transitions/explanations)
• Does the documentation accurately reflect, and respond to, the
  intellectual, technological, professional, educational, and/or personal
  characteristics, interests, and goals of its target audience?
• Does the documentation convey a tone that's appropriately professional, yet somewhat informal -- and always clear and direct?
• If applicable, are sample projects representative of the
  program/task and accurately reflective of the documentation's target
  audience?

Writing and design

• Is the documentation as a whole clear, direct, concise, and accurate in its written presentation of the documented program/task?
• Does the documentation follow the conventions of software documentation (see sample documentation from Week 2 calendar)?
• Are headings, sub-headings, body copy, and labels visually distinct
  from each other? Remember, headings and sub-headings need a sans serif
  typeface, such as Arial; and body copy is generally presented in a
  serif typeface, such as Times New Roman (though Arial is OK for body
  copy, especially in a web-based document such as a website, online help
  system, or PDF document).
• Are the steps within the documentation clear, direct, concise, and accurate in their written presentation? Are all necessary steps included?
• If the documentation presents two or more sub-tasks that comprise a
  larger task, does it incorporate sub-heads and separate numbering
  systems? Does it include transitions that connect related tasks, while
  signifying the need to separate these sub-tasks?
• Does the documentation include an appropriately descriptive, action-based title
  that effectively identifies both the program and a specific task? If
  applicable, does the title also identify a specific project and/or
  target audience?
• Does the documentation include a brief introduction
  that identifies the task(s) presented within? If applicable, does the
  introduction specifically identify expertise, programs,
  hardware/peripherals, files, and other items that the user needs -- and
  do so before the first step?
• Do written steps specifically refer to accompanying screenshots?
• Do screenshots to represent each time the user's screen changes in completing written steps?
• Are screenshots presented below steps/results, thereby helping the document maintain a continuous downward reading flow?
• Are screenshot images crisp -- and are they of appropriate size?
• When necessary, are items within screenshots correctly and effectively labeled?
• Do steps and/or results and their corresponding screenshots appear on the same page?
• When necessary, does the documentation make effective use of notes and/or hints -- and are they clear, direct, concise, and accurate in their written presentation?
• Are notes and hints clearly separate from actual steps?
• Are steps the only items numbered?
• When applicable, does the documentation make effective use of transitions between steps within a single task and/or sub-tasks within a larger task?
• When applicable, are sidebars presented in a way that ensures that they're separate from the documentation's main body -- especially steps/results?
• When applicable, does color direct
  appropriate levels of attention to items for which it's applied? Does
  it enhance the user's ability to complete the documented task?
• If the documentation is presented within a brochure, are related
  items grouped within the same panel, or visually connected panels, as
  much as possible?

Usability

• Does the document as a whole acknowledge the target audience's
  characteristics, purpose(s) for accessing the document, and meet its
  intellectual, vocational, personal, and/or creative needs?
• Does the document allow users to effectively move back and forth between reading and completing the documented task?
• Does the document allow users to smoothly proceed from the
  top/beginning of the document (and/or individual pages) to the
  bottom/end?
• Does the document take into account certain user characteristics,
  such as limited literacy/aliteracy, ability to use written text and/or
  images, language issues, disabilities (learning and/or visual), and
  overall familiarity/comfortability with technology and/or documentation?
• Does the document present all necessary steps and descriptions of
  results? Does it include additional information only when necessary,
  and without excessive details/explanations?
• When encountering or addressing issues or tasks that go beyond the
  scope of documentation for a specific task, or a series of connected
  tasks, does the document direct users to hypothetical or actual
  documents that cover these items?
• Do visual elements -- such as images, color, and page formatting --
  enhance, without detracting from, the user's ability to access and use
  the documentation?