Picking the right format to publish your help files can be tricky, especially if you’re creating your first help manual and you want to avoid the biggest mistakes first time help manual authors make. The right format determines if your users have access to your help files exactly how and when they need it. If you’re using a help authoring tool (and you should because they make it easier to write better help documents in half the time), publishing in multiple formats should be no trouble at all. The big question we’re answering today is, should you publish a print manual (hard copy), or a screen manual (PDF, CHM, Web based HTML, eBook format…).
What’s the worst mistake you can make as a first time help manual author?
A good help manual is user-friendly, and contains clear instructions that users can find and use easily. But if you’re a first time help manual author, creating a good one can be a tough task, especially if it’s your first technical writing project. Interestingly, every great help manual writer had their first moment too, and made several mistakes on their first attempt. We’ve compiled these mistakes, so you wouldn’t repeat any of them. Thankfully, you can learn from these mistakes and create a top-notch help manual on your first attempt.
Let’s face it, help documentation today has a terrible image. Almost everyone you talk to about it has a bad impression of help manuals. There are lots of different reasons for this, some of the most common are:
It doesn’t answer the questions you have
You can’t find the answer even though you know it’s in there somewhere
Almost everyone has at least one help related horror story to tell. Whether it is about trying to understand a product when the help manual has been written in such poor English that it is unintelligible, or a product that has shipped with a manual for entirely the wrong model. Perhaps the story is about one of those manuals that are packed so full of details that there is too much information and it becomes almost impossible to find the answer you need quickly. There are many ways that help manuals can go wrong but in general they can usually be broken down into two main areas:
The manual is out of date or has the wrong information
The manual is poorly written or is difficult to navigate
Writing help documentation can be a tricky process. You need to learn to think like a product user not a developer. As the person responsible for writing the help documentation you may well have been involved with your product for a while, and have become very familiar with how it works. This is useful when writing help documentation but it can also be a disadvantage as you approach the product in a different way to those looking at it for the first time. What may be obvious to you may be a complete mystery to someone without your prior experience of the product, or knowledge of the design process.
Launching a new product takes both time and money, in any business both of these are generally in short supply. There are always pressures to reduce costs and get the product complete and ready for sale at the earliest opportunity. Sometimes when looking for ways to keep costs to a minimum it can be tempting to think of a help manual as being an extra expense that should be produced as cheaply as possible. It is a common belief that most people should be able to work out how to use a product by themselves and if they do have any difficulties they can always call your help-desk for assistance. This error in thinking may well be one of the biggest mistakes made by businesses today. No-one can deny that producing proper help documentation does involve some cost, but to consider the cost without looking at the savings incurred by your help manual is to look at only half the picture.
Writing help documentation can be a very long process. If you have a complicated product to explain it’s not unusual for them to be several hundred help pages, and even a fairly simple product may need a manual of 50 or 100 topics. It isn’t just the length of help documents that can make them complicated to write. If your manual is going to be useful to your readers then you need to make sure every function of the product is included in the documentation, and that every aspect of the product is described accurately, and in a way that will be helpful to your end user. With so much information to include, organizing your help documentation and completing it in a timely manner can be a serious challenge for any technical writer. Fortunately there is a way to write help documents faster, include everything you need to cover and still create a high quality professional document that can be produced in a variety of formats.
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.