Documentation Quality Checklist

When reviewing Technical documentation, online help written by yourself or by a colleague, it is especially difficult to maintain an objective, unbiased view.

The following checklist aims to help you bear in mind the key factors.


Goal-oriented approach 

Most of the time end user read technical documentation or online help is when they have been stuck with a task. Therefore, they will be looking for a description of exactly that task in the documentation.

• Does the documentation structure reflect the technical architecture of the product (= poor) or does the documentation reflect the goals and tasks of the user (= good)?
• Does the documentation tell what you want to say (= poor) or does it tell what the user wants to know (= good)?
• Does the documentation describe what the user can see (= poor) or what he or she cannot see (= good)? Does the documentation describe the product (= bad) or its use (= good)?

Clarity

• Is the structure simple and clear? Or are there chapters, subchapters, subsubchapters, subsub-subchapters, ...?
• Does the sequence of chapters reflect the frequency of use? Do the more important topics come before the less important ones? Do the general topics come before special issues?

Direct access

• Is the text clearly structured with subtitles? Or are there many long, verbose, crowded texts?
• Does every paragraph focus on one topic only, or is the information mixed up?
• Are instructions clearly numbered step-by-step?
• Can the user select what he or she wants to read in a specific situation: concepts, procedures, or parameter details? Or are information types mixed so that the user always must read everything?

Navigation and search

• Is there a clear, user-friendly navigational concept, or are there just links "from everywhere to everywhere"?
• Is there a manually authored index or is there just an automatically generated index?
• Does the index contain synonyms? (Example: Would you find a topic named "Vehicles" also if you were searching for "car", "truck" or "motorcycle"?)
• Is the index a multilevel index and are all index terms unique? Or are there terms that point to more than one topic, leaving the user with the trouble to choose?

Tone, unambiguousness

• Does the text convey confidence and a sense of security, or is it rather intimidating?
• Are there clear instructions that address the user directly (example: "Click ... to ...") or does it remain unclear who must act: the human or the machine (example: " ... must be carried out")?
• Are there any phrases that leave open whether the user must act (required action) or may act (optional action). (Examples: "You should ...", "It might be necessary to ...")?
• Do all titles tell in advance what will be covered within a topic or chapter? Or does the user have to guess and read the first paragraphs just to find out that this is the wrong topic. (Typical examples of this are topics with he heading "Overview". Nobody can tell what these topics are about before reading.)
• The rules for titles also apply to link titles in online help. Are they clear enough to tell where a link will take the user? Can the user assess whether it is worth the click before he or she leaves the topic?

Consistency, terminology

• Do all documentation components of a product line follow a common concept, or does the user have to get used to different documentation all the time?
• Are technical terms used consistently, or are there several names for the same thing?
• Do the terms used in the documentation match the terms used on the device / within the software?

Structure in detail

• Do the structure and the writing style make it easy to find and to comprehend the provided information? Is it possible to access single parts of information selectively?
• Do the most important things come first?
• Does the information that every user will need come before the information only some users will need?
• Does the most frequently needed information come before the information that is only occasionally needed?
• Does the general information come before the specific information?
• Do things that belong together stand together?
• Are the keywords at the beginning of the sentences?
• Are sentences short and simple? Can they be understood also by nonnative speakers?
• Is there only one piece of information per sentence?
• Are there any empty phrases and filling words that could be left out?

Layout

• Does the layout look professional and functional? Or is it rather colorful and crowded, and takes off attention from the content?
• Does the layout support scanning and skipping?
• Does an online document use fonts that are suitable for on-screen reading (non-serif fonts)?
• Does an online document reserve the underline attribute exclusively for hyperlinks? Can the user immediately see what is clickable and what is not?

Authoring process, updates and translations

• Are the documents generated with the help of a suitable authoring system, or are things fiddled manually? Can the documentation be updated and reproduced with little effort? For example, have there been set up any page break rules within the authoring system? Or will the layout have to be redone manually after each update and translation?
• Are both the authoring system and the file formats ready for the future?
• Are the texts written in a translation-friendly way?
• Do file formats, authoring system, and document structure support single sourcing, so that additional formats, media, and versions can be produced from the same source?

Use of specific media features

• How close and how efficient is the integration of online documentation with the software? Can the user just open a PDF? Or is there some sort of context sensitive or even embedded online help?
• Is the online documentation just an on-screen manual or does it make use of the great possibilities online media provide: interaction, animation, and personalization?