A Dozen Techniques to Improve Your Software Online Help

Dennis Crane

First published in the ASPects (ASP Newsletter), November 2005.

There are several main reasons why putting your software manual on-line is necessary. It makes your web-site attractive for search engine crawlers and therefore brings you targeted traffic from Google, Yahoo!, MSN, and other search engines. A good online help manual presents your product as serious and credible. Moreover, if a user faces difficulty using your software and asks for technical support, you may easily resolve the issue by referring that user to a certain page of your online help. Simply give the page's URL. With just one click the user will see screenshots and explanations which will help them to resolve the issue.

Many software vendors, from large companies to independent developers, clearly understand these reasons. They made their help systems a part of their web sites by aiming to attract more prospects and to generate more sales. But even a sketchy analysis of a dozen manuals available online discloses many common mistakes which may reduce the effect of this very powerful tool. The main reason for the mistakes is incorrectly considering an online manual as a standalone document that the user can download or read on the web. The right approach is to make your help an integral part of your web site. This is a simple task if you follow these rules:

Make pages, not a file

The most common mistake I have noticed on many software vendors' web sites is they only offer their manual in a single file: PDF, CHM, RTF, etc. Certainly it may be very convenient for users to download a product manual file and use it on the desktop, especially if the manual is too large to be included in the software setup package. But having an online manual is not the same as having a manual online. There is a difference!

It's very smart to allow users to download a complete manual as a single file. However a single file may attract only a few new visitors from search engines, even if their crawlers are able to index your PDF or RTF. Also the single file is almost useless for your technical support needs. For instance, you cannot point users to certain sections of your help system by simply giving them direct URL links. To get the maximum effect out of your help system for new users and technical support you should make it a part of your web site. Split the manual into many HTML pages. Almost all help authoring software allows exporting your help content into HTML format. Each page should contain a topic, section or chapter of your manual. Having many pages which are relatively small is easier for reading, navigation, and bookmarking. However, don't make a lot of little dinky (single paragraph) pages that people must roam through to figure out the solution to their problem. Each page should completely cover a certain topic enough to solve a certain task. Furthermore, a page with topical content is perfect bait for search engine crawlers.

Follow common style

You have exported your help file into a set of HTML pages and are ready to upload them to your server. Stop! Check the look of the pages. The set should follow the common style identified by your corporate identity and branding.

Modern help authoring tools allow customizing the appearance of pages by means of CSS or visual template collections. The online manual should correspond to your web site style. Use the same colors, themes, fonts, and corporate graphics. Otherwise, the whole project will look like a patchwork quilt. This is not good; it's far better to look well-managed and consistent.

"Where am I?" or don't ignore navigation

Following common style is not limited to just using the same colors and fonts. To plug your manual's pages into the web site structure you must add the top level navigation to them. Use the same top level menu that you use on all pages of your site.

There are two key benefits of this technique. First, this also makes your web site appear solid, consistent, and well thought out and therefore works for your business credibility. Second, the top level navigation menu will bring new targeted leads from your manual pages to your product main pages. The prospects that have come from search engines are likely looking for specific task solutions that probably are described in your online help. Then they will want to know more about the product that offers that solution. Put under their nose direct links to the software description page, to the trial download area, to the pricing and ordering info, and to the main page of your web site. Let them know more about your company. Let them know about your software. Let them download it. Let them buy it.

Besides offering prospects a top level menu, you must provide them with an easy way to navigate amongst the sections of the manual itself. People feel more secure if they see the table of contents along with the page content. Through this internal menu they may easily realize where they are and what related topics exist, and easily jump there.

Avoid frames

At first glance, using frames seems the perfect way to organize the internal menu of the help. Certainly frames are convenient for web site programming and maintenance because you may keep your menu in a single file and show it in a separate frame. Nevertheless, there are several disadvantages to using frames in your online help. When a visitor comes from a search engine to one of your help pages, they will see only that page's content but will see neither top-level navigation nor online manual menus because they were intended to be shown in other frame windows. The people who come from external pages will fail to easily jump to other sections of your web site and read about your products and related services.

If you still prefer to use frames then you must use a workaround. One of the approaches is to plug a special JavaScript code into every page of your web site. The script will determine if the page is showing in the frame or in the browser's main window. If there is no frame detected then the script will build the frame structure, will load the menu pages in the corresponding frames and will finally reload the current page in the appropriate frame. So the user will see the target page along with other elements of the web site. Such dynamic redirection works for real visitors but doesn't work for web spiders that will crawl your online help pages. Most of them cannot parse JavaScript code and therefore cannot access menus to jump to other pages of your manual. For search engines your online manual's pages will look like separate files that are not linked to each other or to the corporate web site. As a result, your help pages will receive lowest page rank and will be shown in the end of the list when someone is looking for related info in a search engine. Almost all SEO and web design gurus recommend avoiding frames. They also recommend putting both menu and content into a single HTML file.

Use direct links, not redirect scripts

Like frames, using JavaScript in menu is another no-no for creating an online manual for your software. Using regular URLs in menu links instead of JavaScript redirecting helps web crawlers properly index your online manual and rank its pages higher.

Assign unique addresses to help pages

And the next important technical aspect of online help authoring is page address format. One of the key rules of search engine optimization (SEO) implies the use of static pages with unique permanent addresses without parameters in them. A page with address installation.htm is usually ranked higher than the same page with address page.php?id=348. Take this fact into account.

Give screenshots

Although one of your aims is to attract search engine web robots that like words you should not forget about real visitors who like pictures. A picture is worth a thousand words. Give as many useful screenshots of your software as possible. This will help current users understand better how your software works and will help prospects to see how it looks before downloading a trial or demo copy. Make your screenshots clear. Explain what each window does and how its controls and elements work. Use callouts, balloons, and special marks. Try to stuff as much information into the screenshots as possible. A reader should look at them and be able to say "Great! Now I know how it works."

Make pages printable

Most likely users would like to print out a certain part of your online help. Sometimes designs that looks great on the display look awful when printed, even on a good printer. Make sure your manual's pages are printable in black and white on at least the two most popular paper sizes: A4 and Letter. Check if there are no big pictures, no color background, the fonts are easy to read, all the content fits the page width, and so on.

Make your help easily reachable

So you have your help pages completed and even uploaded to the web server. How do you make them visible to web spiders and to live visitors of your web site? Most of the software vendors make the same mistake. They think the manual is something unimportant that nobody needs. They hide the help section so deep in the website that a visitor has to make a dozen clicks to reach the help index page. This is wrong! Your manual is important and must be reachable in two to three clicks. The best approach is to place several links to your manual in different sections of your web site: on any product description page, support page, and download page. These are the pages where users expect to find online help. Show them your help content masterpiece.

Make your online manual searchable

If your software is complicated and its help includes hundreds or even thousands of pages then you must add search capabilities to your online manual. From a user's point of view it's more convenient to search a required topic by keywords rather than to look through the endless list of topics in the menu. The easiest way is to add a third-party search script to your online manual. For instance, Google offers Free WebSearch script that you can copy and paste into your HTML code to allow people to search within your site. However, you won't have full control over the third-party scripts and their search results may confuse you and your users. It's better to write your own search script on which you will have total control. You can customize it according to your needs. This top-notch technique requires significant effort and may cost some money if you decide to outsource it. But the result is that you will have a powerful information resource that will effectively work for you and for your business.

Create a word map of your help

Make a special Index page that contains all the significant words with direct links to the pages where these words are in your help files. The Index page has two main functions. First, it simplifies the topic search by keyword for users. Second, the Index page will serve as a map of your online help for web spiders and will assist them to crawl all the pages of your manual.

Make your help extendable

You may be surprised to discover that your online help can become live. You can make it the center of an online community. Just allow your software users to extend your help pages themselves. A good example is PHP online documentation. It allows users to post their comments, code samples, and recommendations. Each page contains tons of valuable information contributed by users. This is a perfect example of how boring documentation may form a live community and promote the product accordingly.

To summarize the above tips: You must consider your manual as an important part of your business model. This is just a set of general recommendations on how to get the maximum effect out of creating online help. Most of the techniques are pretty easy to implement if you use good help authoring software. Apply this advice and make your customers feel happy, increase your web site visibility, attract new prospects, and generate new sales.

Dennis Crane, the author of the Dr. Explain software, specializes in help authoring software development. He is online at https://www.drexplain.com

You are permitted to reprint this text as long as it includes copyright notice and link to our web site.