A Dozen Techniques to Improve Your Software Online Help by Dennis Crane
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 manual makes your product 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 settle the case.
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 a bunch of common
mistakes which may reduce the effect of this very powerful tool. The main reason
of the mistakes is incorrectly considering an online manual as a standalone
document that user can download or read on the web site. The right approach is
to make your help a part of your web site. This is a pretty simple task if you
follow these rules:
Make pages! Not a file
The most common mistake I noticed on many software vendors' web sites is that
they 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. Feel the difference!
It's very smart to allow users to download a complete manual as a single file.
However a file may attract just a few new visitors from search engines, even if
their crawlers are able to index your PDF or RTF. Also the file is almost
useless for your technical support needs. For instance, you may not point users
to certain sections of your help system by simply giving them direct URL links.
Hence to get the maximum effect out of your help system you should make it a
part of your web site. Split the manual into many pages and convert them into
HTML. Almost all serious help authoring software allows exporting your help file
into HTML format. Each page must contain a certain section or a chapter of your
manual. Many pages which are relatively small are easier for reading,
navigation, and bookmarking. You nevertheless must keep the balance. Don't make
a lot of little dinky pages that people must roam through to make up a required
solution. 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
Well, 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 must
follow the common style identified by the corporate identity.
The modern help authoring tools allow customizing appearance of pages by means
of CSS or visual template collections. The online manual must correspond to your
web site style. Use the same color 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 steady, well-managed, and consistent.
"Where am I?" or don't ignore navigation
Following common style is not just using the same colors and fonts. To plug
manual's pages into the web site structure you must add the top level navigation
into them. Use the same top level menu that you use on all pages of the 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. Secondly, 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 toplevel menu, you must provide them with an easy
way to navigate among 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. So the people who come from external pages will fail to
easily jump to other sections of your web site and to 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 on a search engine. Almost all SEO and web
design gurus recommend avoiding frames and put 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 third important technical aspect of online help authoring is page
address format. One of key rules of search engine optimization (SEO) implies to
use 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's 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 juicy 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 info into the screenshots as possible. A reader must look at them
and 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 design that looks great on the display is awful when printed even on a
good printer. Make sure that your manual's pages are printable in black and
white at least on 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
to make them visible to web spiders and to live visitors of your web site? Most
of the software vendors make the same mistake. They thought that 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 product description page, on support
page, and on download page. These are the pages where users expect to find an
online help most of all. Show them your help-authoring 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 menu. The easiest way
is adding a third-party search script to your online manual. For instance,
Google offers Free WebSearch script that you can copy-paste into your HTML code
to allow people searching 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 at any moment. This
top-notch technique requires significant efforts 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 encountered. The Index page has two
main functions. Firstly, it simplifies the topic search by keyword for users.
Secondly, 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 but the online help may be live. You can make it a 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 how to get
the maximum effect out of your 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.
About the Author
Dennis Crane, the author of Dr. Explain software, specializes in vertical
markets software development. He enjoys bass and ice fishing and is online at
http://www.drexplain.com