Everyone understands the importance of accurate, up-to-date help documentation. The only way to get the best out of any product is to read the manual and find out how to use every function properly. The difficulty faced by the developers of many products is choosing which formats they should produce their help documentation in. It used to be the case that a printed manual was considered sufficient for most products. In recent years the printed manual has frequently been replaced by either a PDF or on-line version, but are these really the best options available?
If you have never written help documentation before then it can seem a little scary. The end-users of your product are relying on you to help them understand every function of the product, and their continued use of the product rests on how successful you are in providing answers to their questions. Here is our 'idiots guide' to writing manuals and help documents. These tips will help you write help documents that cover all the details you need to include and that can be easily understood by your end-users.
What are the major product related costs for your business? Everyone knows that creating a new product costs money. There are costs involved in designing, testing, manufacturing the product, and also in getting the product to customers. All of these things need to happen if you are going to create a product which can be sold and produce an income that will allow the business to prosper.
If you have ever tried to write any type of documentation then you know that the process isn't as easy as you might think. Writing high quality help documents or manuals takes time and a lot of planning to make sure all the functions of the product are correctly explained. Many technical writers will have heard about help authoring tools, and some may even have thought about giving them a try, but been unclear exactly what the benefits are of using a help authoring tool compared to employing a standard word processing package. Here are three ways that a help authoring tool can help you to write better help documentation.
In short, HATs are software developed help authoring programs employed by technical writers to develop help documents, technical manuals and solutions.
As an example, take any product in today's competitive consumer marketplace world — be it an automobile, a home appliance, computer software or whatever product-type that requires operational instruction, functionality performance or assembly by the consumer — and you'll usually find an easily forgotten "behind-the-scenes" initiative by dedicated professionals that has led to the successful emergence of that product for sale.
Such is the case — and never to be lightly regarded — is the set of user help documentation that typically accompanies the product; with the ultimate goal of maximizing the usage and functionality experience for the buyer, as well as reducing support costs for the producer. Clear and effective user instructions can often make the ultimate difference in buyer appreciation, loyalty and acceptance as it can often "make or break" a product's success.
How often have you spent ages searching a help file for something that you know should be there, but you just can't find? Help documentation is usually the first place that we look when we don't know how something is supposed to work. If the information in the help file is not clear, or even worse misleading then we are just going to end up frustrated, and maybe even rejecting the product for something easier to understand.
Creating product help documentation has many similarities with a typical student project. A student project will often need to:
- Discuss a topic in depth, covering each aspect of the topic thoroughly
- Break a subject down into clearly identifiable sections
- Include detailed references supporting the conclusion of the project
- Provide a complete index covering the topic under discussion
All of these tasks can be managed much better in help authoring software than in a conventional word processing package. If you write a student project in Microsoft Word then you have little choice but to start at the beginning of the subject and type the whole thing all the way through. That approach makes project writing tricky and very time consuming.
Writing help documentation is hard work, a technical author needs to clearly explain every function of the product. The documentation needs to be written for a wide range of product users, not all of whom will be approaching the product with the same level of technical expertise or expectations.
Despite these consideration, in many cases technical authors find that writing the help documentation is the easy part of the process. Once they have written down everything they need to say to cover the topic properly they then need to format it so that it is accessible and easy to read in a variety of formats. Formats that might be required include PDF, Word, online HTML, perhaps HLP or CHM as well. The whole formatting process can be very time consuming when what most technical authors really want is to concentrate on writing really good help documentation and not have to spend ages worrying about how their pages display on different devices.
When the documentation is finally completed that is often still not the end of the process as every time the product is revised the documentation has to be changed to reflect the new or updated features.