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 reviewing user manuals or online help files written by yourself or by a colleague, it’s difficult to maintain an objective, unbiased viewpoint. The following checklist helps you maintain this objective viewpoint and bear in mind the key factors.
Although you may be very proud of the work you did on a product as a developer, most users have no interest in how your product works. Users just want to get their job done and read manuals only when they are stuck while trying to perform a task. Within the documentation, they are only looking 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 describe what you want to say (= poor) or does it describe 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 (= poor) 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 only on one topic, 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 also find a topic named “vehicles” 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 dilemma of choosing?
▪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 only to find out that they are reading the wrong topic? (Typical examples of this are topics with the heading “Overview.” Nobody can tell what these topics are about before reading them.)
▪Are all links clear enough to tell where they will take the user? Can users assess whether it’s worth following 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 comprehend the provided information? Is it possible to access individual pieces of information selectively?
▪Do the most important things come first?
▪Is the information that all users need placed before the information that only a 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?
▪Are things that belong together grouped together?
▪Are the most important keywords located near the beginning of a sentence?
▪Are sentences short and simple? Can they be also understood by nonnative speakers?
▪Is there only one piece of information per sentence?
▪Are there any empty phrases and filler words that could be left out?
▪Does the layout look professional and functional? Or is it colorful and crowded and does it distract from the content?
▪Does the layout support scanning and skipping?
▪Does an online document use fonts that are suitable for on-screen reading (sans-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?
▪Have the documents been generated with the help of a suitable authoring system, or have they been manually tweaked? Can the documentation be updated and reproduced with little effort? For example, have there been any page break rules set up 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, the authoring system, and the document structure support single source publishing so that additional formats, media, and versions can be produced from the same source?
Did you benefit from this guide? Please help to keep it free also in the future. Buy a copy of the PDF version (approx. 140 pages).
This page was last updated 12/2013.