Dear Help Author,
The title of this document would rather be, "7 keys to make your help files contribute to the sales of your software products." Please read the disclaimer to know more.
Disclaimer and the targeted audience: This is by no way an introduction to Windows help authoring. I am also not claiming that these are the only and the most important keys to creating better help files. What I am presenting is my own personal collection of some key points on Windows help authoring. I hope they make an interesting reading. If you find them useful, please drop me a note. I am not an expert in technical documentation. I am a shareware author and in the course of preparing help files for my own products, I have discovered these key points and have found them to be important. Hence, this document is targeted towards beginning help writers, especially shareware authors who often have to do all the work of documenting their program in addition to writing code. In the process, they might miss on certain key elements which go towards making their help files contribute to the sales of their products. If the tone of this document sounds patronizing, believe me, it is not intentional. This is simply my style of writing, and I am not claiming that I am superior in any way.
Have you ever wondered whether the users of your software really read the help files that you so meticulously created? If they don't, all your carefully crafted topics go waste. Here, I am giving you some key concepts based on my own experience as a shareware author. They will benefit any help author, and they may even increase sales of your own software product!
1. Make your important topics accessible in many ways
This is an important tip, and that's why, it's the first on my priority list. Suppose, you worked very hard on your "Introduction" topic, and you believe that you will make a few sales just on the power of that topic. But, are you sure the user will even look at that topic? In my experience, users only see the help file on a need basis. They don't read it like a book. What is the solution then? Simple. Make the topic accessible from many places. One way is to keep a link to that topic at the bottom of all the important topics which are likely to be visited by the user. For example, if you have a topic called "Questions and Answers" which is more likely to be read, put a link at the bottom which points to the "Introduction."
You must also look in your software product for places where you can point to that topic. For example, on your main help menu, keep a separate menu item called "Introduction." It would also help to give this topic a more interesting name.
2. Use orphans at the top of help contents to highlight important topics
If you are a help author, you must already know how to write Help Contents which appear in the Help Topics dialog box. The contents come from the CNT file which you create either with the Microsoft Help Workshop or by using a help authoring tool.
You might think that each item that first appears in Help Contents can only be a expandable heading and not a topic. For example, if you have some introductory topics, you will put them under a heading called "Introduction to XYZ product." The problem is that the user may never expand that heading, thinking that it contains trivial topics. The result is that one of your important topics like "How to order" remains hidden, and the user never sees it unless he expands that "Introduction" heading. Some help authors (I have actually seen it) aggravate the problem by putting all their top level headings under a main heading called "Help for XYZ product." In this case, the user has to make an unnecessary click, just to see the top level headings. Never do that! It is too irritating.
Now, back to the main problem. How do you make sure that the user always sees your important topics, such as, "How to order" or "Purchase benefits." Simple. Put them at the top of your help contents and make them level 1, the top most level. If you now see your help contents, the topics will always be visible at the top. The help authoring guide doesn't give this information, and it is an important technique that I use. However, please make sure that you don't do this later in the Help Contents. It won't work. It works only at the top of the Help Contents.
3. Remember, the content is more important than the formatting and graphics
The soul of a document is its text content. Even if your graphics is excellent and the formatting is superb, your help file will be ineffective if you don't spend most of your energy in your text content. If this were not true, in advertising, no one would hire an expensive copy writer--a fact that most of us ignore. I am not saying that the graphics and formatting is unimportant. But, they are secondary to the text content. First, concentrate on your text content. Once it is finished, add formatting or graphics to enhance it. To improve your text content so that you sell more of your product, consult some good copy writing books for inspiration.
Finally, if you have understood and agree with what I said, you should not start your help projects with help authoring tools which give more importance to the WYSIWYG appearance and graphics features. Instead, look for help authoring tools which help you brainstorm the ideas and text of your topics. When you have finished the text content and the structure of your topics, only then would a WYSIWYG authoring tool be useful to enhance the appearance.
4. Use hypertext links liberally but intelligently
A well written and well connected Windows help file can be a pleasure to read. It would also reduce lots of your support calls. You will find lot of documentation on the World Wide Web that lists Do's and Don'ts of hypertext links. For example, it says, the reader should know where he is in the documentation, how many levels deep, and so on. Various theories are presented. But, in my opinion, experience is the best teacher. The more help files you see, and the more help files you write, you will get an idea of good and bad hypertext links yourself. I won't bore you by harping on that theme. It's just like teaching Do's and Don'ts of English language and grammar. Those who teach, seldom attempt to write stuff which is actually read and enjoyed by millions.
Once you get a feel for what is good hypertext, use a hypertext authoring tool which doesn't force you to interrupt your writing thoughts when creating new links. For example, suppose you have written five complex help topics which are to be interconnected to each other by several hypertext links. You would want to actually create these links, move them around, remove some of them and test them to see whether they satisfy you as a reader. Now, for each such link insertion, if a help authoring system requires you to enter a target topic name, think up of a context string or a number to assign to the target topic and then insert a link, it will hinder your thought processes. In such a case, you will end up using insufficient number of links, perhaps pretending, that too many links are not good. No. A good tool should allow drag and drop, copy and paste of topic links in to a block of text. It should manage context strings internally. In fact, inserting links should be so easy that you use links liberally in your normal writing activities too.
5. Keywords are more important than you think
If you are a good help author, you would realize the importance of keywords. The experience of writing good keywords index comes only when you look at the help files written by others. I have seen important keywords missing in the help files of even commercial products. The effect can be so frustrating that a user may not buy your product. You will also get more technical support queries if your keywords are inadequate. Adding keywords is the never ending process in a help product's life cycle. You can never have enough keywords, but you can try. Always think from your user's point of view of what he may be looking for. For instance, if he wants to buy your product, he might look for "Buy," "Purchase," "Order," or "How to buy." The new Windows 9X/NT help created with HCW has many features for keywords. Make sure that you understand all of them. Use a help authoring tool which allows you to easily review keywords, to assign keywords to topics, to point keywords to the middle of topics and to compare keywords assigned to different topics.
6. Eliminate surprise launches of external programs and web sites
You may already be using links to launch other programs and web sites in your help documentation, especially to the order forms. While jumping to a web site may be easy in a country like United States where computers are often left connected to the Internet, it may not be so elsewhere in the world. Unless your product is such that it requires Internet connection itself, it is best to somehow indicate to the user that he would be going to a web site or would be launching an external program. This can be done by creating a popup topic which shows the final URL link connecting to the web site. I will explain. For example, suppose you have a link "Questions and answers." The user might expect to click on that link to see actual FAQs. If instead, you directly try to launch the web browser to take him there, he might be surprised and irritated. The correct link should have been "Go to Questions and answers web site." Or, you could also create a popup topic which shows the actual URL link, and if the user clicks on it, then and only then should you launch the browser.
7. Don't be afraid to write big help files
Nothing can be more irritating than a help file which just lists the program's menu operations. It is as if the author has just created the help file as a dummy place holder to complete his product. He is literally trying to satisfy the requirement that no product is complete without a help file. For the sake of such authors, the rule should be rewritten, "No product is complete without a help file that really helps." It's wrong to believe that smaller help files are easier to understand. While I agree that the procedures should be written in a compact way, often in secondary windows, I feel that many help topics require a detailed explanation. There is no substitute for them. You will learn that when you get those technical support calls.
Just duplicating the printed manual is another mistake. A help file and the printed manual are two different mediums, one is hypertext and the other is not. No, your help file must take advantage of hypertext. Then, on top of it, if you don't have a printed manual, you can present a manual like interface in your help file by using the Help Contents and the browsing sequences wisely.
If you have any comments, you are welcome to send email to me.
To your success as a Help Author,
Sanjay Kanade
Is writing a help file any different from other forms of writing?
Developer/Publisher of HelpHikes Pro
A Writer's Help Authoring System
Copyright 1998-2003, Sanjay Kanade
All rights reserved