16 Reasons Why Only Your Users Do Not Read User Documentation
Dennis Crane
Nobody reads help files!
Are you sure?
In the ten years that we’ve been developing Dr.Explain, a leading-edge tool for creating help files, we saw hundreds of our customers’ projects. Our technical support team mostly receives user documentation for software products with requests to help implement some tricks. When talking with our customers, we ask them all kinds of questions about their projects, business areas, products, and audiences.
Based on that experience, we can draw a lot of conclusions, including this one: Users do read user documentation. In many cases, users frequently consult with such documentation. In some projects, it is a vital component of the product or services.
However, sometimes people do not use user documentation. In most cases, the reasons are as follows.
The documentation is difficult to find
1. The product page doesn’t contain a link to the documentation.
After deploying an online help system on the website, the software developer often forgets to add a link to it on the product’s main page. As a result, the users will be unable to find that help on their own. The only chance to access that help is by contacting the technical support team, which may share a link to the online help. But to ask for support, the users must be strongly motivated. Most people lack that motivation, so they will simply give up. Luckily, this problem is easy to solve: Just add links to the online help in the menu of your product’s website, as well as on your technical support and product features pages.
2. The link to the online help is hard to find.
The link to the online documentation exists but is located at the very bottom of the last page of the website. As a result, it is impossible to find that link, so it’s as good as no link at all.
3. The user documentation is not included in the product distribution package.
Sometimes a software or hardware developer does not include the user documentation in the product (on a CD or DVD disc in the box). It’s good enough if the product includes a note saying that the documentation is available for downloading or reading online on the product’s website. But sometimes there is no such note, and people who need that help will be in for a multi-level quest. Believe us, the users will be very unhappy about that! At the very least, make sure that basic user documentation is always installed together with your product.
4. There is no Help menu or button in the user interface.
In this case, even if a help file is included in the distribution package, there is no user interface item to tell the user about that. There is no Help item in the menu, there is no Help button in any of the dialog windows, and there is no Help shortcut among the application’s shortcuts! At best, a few technical savvy users might look for documentation in the application installation folder. As a result, the technical writer’s efforts will be wasted. So please carefully go through your application’s user interface and think about where you can add controls that open the help file.
5. The F1 key doesn’t work in the application.
Many users of classic applications are used to pressing the F1 key to open the context help. If the F1 key doesn’t work because the software developer didn’t bother to create a context help, most users won’t try other ways to find the help. By the way, have you tried pressing F1 when using your application?
Incompatible help file format
The help file format is incompatible with some environments.
Surely, the help file must be compatible with the user’s platform. We recommend using a native format, if possible. For example, CHM is a great choice for a Windows application. That format is supported by the operating system, which has a built-in CHM viewer. However, CHM is not native to Mac OS, Ubuntu, etc., so better to use a different format for those operating systems. If you develop cross-platform applications, always try to adapt the documentation to the user’s platform.
7. The document format is difficult to access on a specific device or in a specific environment
User documentation in the HTML format published on a website is good enough for most cases. Users can access online help via a web browser even fr om a low-end smartphone. However, keep in mind that sometimes Internet access is unavailable or very limited (among other things, it might be very expensive in roaming). For such cases, better create a local help file that is accessible offline. For example, provide the user documentation in a PDF or even plain-text file.
8. Additional software is needed to read the documentation.
The PDF format is a de-facto standard for documents intended for viewing on different platforms. Nonetheless, keep in mind that PDF is not native to any operating system. To read a PDF document, the user has to install Adobe Reader or a third-party PDF viewer. So if your application is installed in a “bare-bones” environment and the user needs to consult with the documentation, make sure that an appropriate viewer is installed.
Navigation problems
9. Lack of full-text search in documentation.
If the user documentation consists of dozens of sections arranged in several levels, it will be difficult to find relevant information, even with good navigation. No one is going to read the documentation from beginning to end! So full-text search is a must-have. If your documentation is in a CHM, PDF, or DOC file, you are lucky. Full-text search is already implemented in the respective document viewers: CHM Viewer (Windows), Adobe Reader, or MS Word. Each of these applications allows the user to search through the whole document.
But when you create an online help system, which is basically a bunch of HTML files, it is up to you to implement the full-text search capability. A web browser allows you to search within the current page only. To let the user search in other sections too, you will need some web scripts. Luckily, there is no need to write the scripts on your own! If you create user documentation using advanced software like Dr.Explain, the full-text search capability will be automatically added to your online help. In this case, you won’t have to learn web programming. So use the right tools to create user documentation.
10. Poor navigation in documentation.
This problem is mostly encountered in online help systems. For example, if the table of contents is available only on the first page and not repeated on the other pages, you cannot switch from one section to another in one click. In this case, if users find a section of the online help via a search engine like Google, they will not see the table of contents, so they won’t know how to go to other sections that might contain other useful information. To avoid this problem, just use the right tools. A specialized software tool can create online help systems with easy navigation. In addition to generating the table of contents, it can add supplementary means of navigation, such as “bread crumbs,” links to the next and previous pages, lists of related sections (“See also”), and keyword indexes.
11. Poor documentation structure or no structure at all
Amazingly, sometimes we see help files or online help systems wh ere text is not divided into sections. But user documentation is not a fiction book intended to be read from cover to cover! When users access a help system, they are looking for answers to specific questions and solutions to specific problems. Possibly, someone currently needs only one sentence and one screenshot out of thousands of sentences and hundreds of pictures! Therefore, organize user documentation properly. Divide it into sections based on users’ needs or the product’s structure. If you do that, your users will quickly find relevant information to solve their current problems.
Besides, it will be easier for you to handle a well-structured project, especially when adding more sections or otherwise updating the documentation.
Poor content
12. The help is not in the users’ native language.
Some users simply cannot read the documentation. If you market your product in different countries, think about localizing it. At the early stages, you can do without localization if your product’s core audience is made of information technology professionals. In this case, it might be sufficient to provide documentation in English only. Thankfully, IT professionals even from non-English speaking countries usually know this language to some extent simply because their work involves reading a lot of documentation and specifications in English. As for other user categories, it’s not that simple. In many countries, even highly educated users, such as lawyers or medical professionals, often neither speak nor read English. For example, if you launch a mass-market product in Brazil, you will have to provide user documentation in Brazilian Portuguese.
13. Poor choice of words in documentation.
Technical specialists are susceptible to professional deformation. You can find the signs of it in many technical texts. We often unwittingly use professional slang, which sounds totally natural for us, when talking to family and friends, when writing letters, and, surely, when creating user documentation. But a text full of technical words may look and sound like total gibberish for the user! So each time you want to use a highly technical term or slang, make an effort and find an appropriate substitution. Always write user documentation in words easily understandable by the users, taking into account their background.
14. Lots of errors in the documentation.
For some people, reading a text full of errors is one of the most unpleasant things. Remember that!
15. Lack of diagrams and screenshots in the documentation.
An old adage says that a picture is worth a thousand words – that’s true! It takes more time and mental effort to understand the documentation that doesn’t contain any screenshots, diagrams, or other pictures. So make the life easier for your users by combining text and graphics. For example, when writing about how to set some parameters in the system, add a screenshot showing the parameters. Make your pictures more lively by using Dr.Explain, which can automatically annotate them by adding interactive, self-explanatory callouts. But don’t replace all text with pictures, try to find a balance.
16. Lack of videos in the documentation.
Users are lazy. It’s neither bad nor good, it’s just a fact of life. We don’t like to read, that’s true. We prefer to watch. Using a video is a great way to show a sequence of actions, a scenario, or changes over time. User documentation that contains videos will be more popular than a conventional one. Unfortunately, the ability to play back a video on the page of documentation imposes restrictions on suitable document formats. For example, you can watch a video on an HTML page, but it’s not that simple with a PDF file. So you have to strike a balance. For example, Dr.Explain, an advanced software tool that allows you to create user documentation in several formats from a single source, tackles the video playback problem as follows: If you ins ert a video from YouTube or other video hosting in to the text, the HTML-based online help system, and the CHM help file will allow the user to watch the video within the page; and the PDF and MS Word documents will contain a clickable frame for starting playback in a web browser.
Here’s the last reason why users do not read your user documentation:
Your product is so bad that even the finest documentation cannot save it
Alas, such things do happen. :)
But surely that’s not about you!