|
Documentation Quality Checklist
|
|
|
Checklist for assessing and improving the quality of technical documentation, especially software documentation such as user manuals, online help files, screencasts, demos and tutorials
When facing the challenge to review user manuals or online help files written by yourself or by a colleague, it’s difficult to maintain an objective, unbiased view. The following checklist aims to help you bear in mind the key factors.
Most users don’t take any interest in how your product works – no matter how proud you are of this as the developer. Users just want to get their job done and read manuals only when they are stuck with a task. Within the documentation they look for a description of just this particular task.
| ▪ | 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 users want to know (= good)? |
| ▪ | Does the documentation describe what users can see (= poor) or what users can’t see (= good)? Does the documentation describe the product (= bad) or its use (= good)? |
|
| ▪ | Is the structure flat, simple and clear? Or are there chapters, subchapters, subsubchapters, subsubsubchapters, …? |
| ▪ | Does the sequence of chapters reflect the frequency of use? Are the more important topics placed before the less important ones? Are the general topics placed before special issues? |
|
| ▪ | Is the text clearly structured? Are subtitles used? Or are there many long, verbose, crowded texts? |
| ▪ | Does every paragraph focus on one topic only, or is the information all mixed up? |
| ▪ | Are instructions clearly numbered step-by-step? |
| ▪ | Can users select what they want to read in a specific situation: concepts, procedures, or parameter details? Or do users always have to read everything? |
|
| ▪ | How close and how efficient is the integration of online documentation with the software? Can users 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? |
|
| ▪ | Is there a clear, user-friendly navigational concept, or are there just links “from everywhere to everywhere”? |
| ▪ | Do all topics of an online help system contain valuable information, or are there topics filled with nothing but links that send users on a wild goose chase? |
| ▪ | Is there a manually authored index or is there just an automatically generated index? |
| ▪ | Does the index contain synonyms? (Example: Could 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 users with the trouble to choose? |
|
| ▪ | Does the text convey confidence and a sense of security, or is it in any way intimidating? |
| ▪ | Are there clear instructions that address users 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 users 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 do users 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.) |
| ▪ | Are all links clear enough to tell where they will take the user? Can users assess whether it’s worth to follow a link before actually doing so? |
|
| ▪ | Do all documentation components of a product line follow a common concept, or do users 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? |
|
| ▪ | 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? |
| ▪ | Is the information that all users need placed before the information that only a only minority of users need? |
| ▪ | Is the most frequently needed information placed before the information that’s only occasionally needed? |
| ▪ | Is the more general information placed before the more 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? |
|
| ▪ | Does the layout look professional and functional? Or is it rather colorful and crowded, and distracts 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’s clickable and what’s not? |
|
| ▪ | 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 source publishing, so that additional formats, media, and versions can be produced from the same source? |
|
Keywords relating to this page: technical documentation - software documentation - user documentation - user manual - user manuals - online help file - online help files - quality - quality criteria - checklist - weaknesses - analysis - usability - user friendlyness - user friendly - comprehensibility - comprehensible - clear - well-written.
|
|
|
|
|
 |
Any questions?
We can give you expert advice and individual training on creating and optimizing technical documentation, especially software documentation.
For information, see: Services
|
No time?
We can create user manuals, online help files, screencasts and all other forms of software user assistance for you.
Top-quality, on time, at reasonable costs.
For information, see: Services
|
|
|
