| There are several main reasons why putting | | | | frame. So the user will see the target page |
| your software manual on-line is necessary. | | | | along with other elements of the web site. |
| It makes your web-site attractive for search engine | | | | Such dynamic redirection works for real |
| crawlers and therefore brings you targeted | | | | visitors but doesn't work for web spiders |
| traffic from Google, Yahoo!, MSN, | | | | that will crawl your online help pages. |
| and other search engines. A good online | | | | Most of them cannot parse JavaScript |
| manual makes your product serious and | | | | code and therefore cannot access menus |
| credible. Moreover, if a user faces difficulty | | | | to jump to other pages of your manual. |
| using your software and asks for | | | | For search engines your online manual's |
| technical support, you may easily resolve | | | | pages will look like separate files that are |
| the issue by referring that user to a certain | | | | not linked to each other, or to the corporate |
| page of your online help. Simply give the | | | | web site. As a result, your help |
| page's URL. With just one click the user | | | | pages will receive lowest page rank and |
| will see screenshots and explanations | | | | will be shown in the end of the list when |
| which will help them to settle the case. | | | | someone is looking for related info on a |
| | | | search engine. Almost all SEO and web |
| Many software vendors, from large | | | | design gurus recommend avoiding frames |
| companies to independent developers, | | | | and put both menu and content into a |
| clearly understand these reasons. They | | | | single HTML file. |
| made their help systems a part of their | | | | |
| web sites by aiming to attract more prospects | | | | Use direct links, not redirect scripts |
| and to generate more sales. But | | | | |
| even a sketchy analysis of a dozen manuals | | | | Like frames, using JavaScript in menu is |
| available online discloses a bunch of | | | | another no-no for creating an online |
| common mistakes which may reduce the | | | | manual for your software. Using regular |
| effect of this very powerful tool. The | | | | URLs in menu links instead of JavaScript |
| main reason of the mistakes is incorrectly | | | | redirecting helps web crawlers properly |
| considering an online manual as a | | | | index your online manual and rank its |
| standalone document that user can download | | | | pages higher. |
| or read on the web site. The right | | | | |
| approach is to make your help a part of | | | | Assign unique addresses to help pages |
| your web site. This is a pretty simple task | | | | |
| if you follow these rules: | | | | And the third important technical aspect |
| | | | of online help authoring is page address |
| Make pages! Not a file | | | | format. One of key rules of search engine |
| | | | optimization (SEO) implies to use static |
| The most common mistake I noticed on | | | | pages with unique permanent addresses |
| many software vendors' web sites is that | | | | without parameters in them. A page with |
| they offer their manual in a single file: | | | | address installation.htm is usually ranked |
| PDF, CHM, RTF, etc. Certainly it may be | | | | higher than the same page with address |
| very convenient for users to download a | | | | page.php?id=348. Take this fact into |
| product manual file and use it on the | | | | account. |
| desktop, especially if the manual is too | | | | |
| large to be included in the software setup | | | | Give screenshots |
| package. But having an online manual is | | | | |
| not the same as having a manual online. | | | | Although one of your aims is to attract |
| Feel the difference! | | | | search engine's web robots that like |
| | | | words you should not forget about real |
| It's very smart to allow users to | | | | visitors who like pictures. A picture is |
| download a complete manual as a single | | | | worth a thousand words. Give as many |
| file. However a file may attract just a few | | | | juicy screenshots of your software as |
| new visitors from search engines, even if | | | | possible. This will help current users |
| their crawlers are able to index your PDF | | | | understand better how your software |
| or RTF. Also the file is almost useless for | | | | works and will help prospects to see how |
| your technical support needs. For instance, | | | | it looks before downloading a trial or |
| you may not point users to certain | | | | demo copy. Make your screenshots clear. |
| sections of your help system by simply | | | | Explain what each window does and how |
| giving them direct URL links. | | | | its controls and elements work. Use |
| Hence to get the maximum effect out | | | | callouts, balloons, and special marks. Try |
| of your help system you should make it a | | | | to stuff as much info into the screenshots |
| part of your web site. Split the manual | | | | as possible. A reader must look at them |
| into many pages and convert them into | | | | and say "Great! Now I know how it |
| HTML. Almost all serious help authoring | | | | works." |
| software allows exporting your help file | | | | |
| into HTML format. Each page must | | | | Make pages printable |
| contain a certain section or a chapter of | | | | |
| your manual. Many pages which are | | | | Most likely users would like to print out |
| relatively small are easier for reading, | | | | a certain part of your online help. Sometimes |
| navigation, and bookmarking. You nevertheless | | | | design that looks great on the display |
| must keep the balance. Don't | | | | is awful when printed even on a |
| make a lot of little dinky pages that people | | | | good printer. Make sure that your manual's |
| must roam through to make up a | | | | pages are printable in black and |
| required solution. Each page should | | | | white at least on the two most popular |
| completely cover a certain topic enough | | | | paper sizes: A4 and Letter. Check if there |
| to solve a certain task. Furthermore, a | | | | are no big pictures, no color background, |
| page with topical content is perfect bait | | | | the fonts are easy to read, all the content |
| for search engine crawlers. | | | | fits the page width, and so on. |
| | | | |
| Follow common style | | | | Make your help easily reachable |
| | | | |
| Well, you have exported your help file | | | | So you have your help pages completed |
| into a set of HTML pages and are ready | | | | and even uploaded to the web server. |
| to upload them to your server. Stop! | | | | How to make them visible to web spiders |
| Check the look of the pages. The set must | | | | and to live visitors of your web site? |
| follow the common style identified by the | | | | Most of the software vendors make the |
| corporate identity. | | | | same mistake. They thought that the |
| | | | manual is something unimportant that |
| The modern help authoring tools | | | | nobody needs. They hide the help section |
| allow customizing appearance of pages | | | | so deep in the website that a visitor has to |
| by means of CSS or visual template collections. | | | | make a dozen clicks to reach the help |
| The online manual must correspond | | | | index page. This is wrong! Your manual |
| to your web site style. Use the | | | | is important and must be reachable in two |
| same color themes, fonts, and corporate | | | | to three clicks. The best approach is to |
| graphics. Otherwise, the whole project | | | | place several links to your manual in |
| will look like a patchwork quilt. This is | | | | different sections of your web site: on |
| not good; it's far better to look steady, | | | | product description page, on support |
| well-managed, and consistent. | | | | page, and on download page. These are |
| | | | the pages where users expect to find an |
| "Where am I?" or don't ignore navigation | | | | online help most of all. Show them your |
| | | | help-authoring masterpiece. |
| Following common style is not just using | | | | |
| the same colors and fonts. To plug manual's | | | | Make your online manual searchable |
| pages into the web site structure you | | | | |
| must add the top level navigation into | | | | If your software is complicated and its |
| them. Use the same top level menu that | | | | help includes hundreds or even thousands |
| you use on all pages of the site. | | | | of pages then you must add search capabilities |
| | | | to your online manual. From a |
| There are two key benefits of this | | | | user's point of view it's more convenient |
| technique. First, this also makes your web | | | | to search a required topic by keywords |
| site appear solid, consistent, and | | | | rather than to look through the endless list |
| well-thought-out and therefore works for | | | | of topics in menu. The easiest way is |
| your business credibility. Secondly, the | | | | adding a third-party search script to your |
| top level navigation menu will bring new | | | | online manual. For instance, Google |
| targeted leads from your manual pages to | | | | offers Free WebSearch script that you can |
| your product main pages. The prospects | | | | copy-paste into your HTML code to |
| that have come from search engines are | | | | allow people searching within your site. |
| likely looking for specific task solutions | | | | However you won't have full control over |
| that probably are described in your online | | | | the third-party scripts and their search |
| help. Then they will want to know more | | | | results may confuse you and your users. |
| about the product that offers that solution. | | | | It's better to write your own search script |
| Put under their nose direct links to the | | | | on which you will have total control. You |
| software description page, to the trial | | | | can customize it according to your needs |
| download area, to the pricing and ordering | | | | at any moment. This top-notch technique |
| info, and to the main page of your | | | | requires significant efforts and may cost |
| web site. Let them know more about your | | | | some money if you decide to outsource it. |
| company. Let them know about your | | | | But the result is that you will have a |
| software. Let them download it. Let them | | | | powerful information resource that will |
| buy it. | | | | effectively work for you and for your |
| | | | business. |
| Besides offering prospects a toplevel | | | | |
| menu, you must provide them with | | | | Create a word map of your help |
| an easy way to navigate among sections | | | | |
| of the manual itself. People feel more | | | | Make a special Index page that contains |
| secure if they see the table of contents | | | | all the significant words with direct links |
| along with the page content. Through this | | | | to the pages where these words are encountered. |
| internal menu they may easily realize | | | | The Index page has two main |
| where they are and what related topics | | | | functions. Firstly, it simplifies the topic |
| exist, and easily jump there. | | | | search by keyword for users. Secondly, |
| | | | the Index page will serve as a map of |
| Avoid frames | | | | your online help for web spiders and will |
| | | | assist them to crawl all the pages of your |
| At first glance, using frames seems the | | | | manual. |
| perfect way to organize the internal menu | | | | |
| of the help. Certainly frames are convenient | | | | Make your help extendable |
| for web site programming and | | | | |
| maintenance because you may keep your | | | | You may be surprised but the online help |
| menu in a single file and show it in a | | | | may be live. You can make it a center of |
| separate frame. Nevertheless, there are | | | | an online community. Just allow your |
| several disadvantages to using frames in | | | | software users to extend your help pages |
| your online help. When a visitor comes | | | | themselves. A good example is PHP |
| from a search engine to one of your help | | | | online documentation. It allows users to |
| pages, they will see only that page's | | | | post their comments, code samples, and |
| content but will see neither top-level | | | | recommendations. Each page contains |
| navigation nor online manual menus | | | | tons of valuable information contributed |
| because they were intended to be shown | | | | by users. This is a perfect example of |
| in other frame windows. So the people | | | | how boring documentation may form a |
| who come from external pages will fail to | | | | live community and promote the product |
| easily jump to other sections of your web | | | | accordingly. |
| site and to read about your products and | | | | |
| related services. | | | | To summarize the above tips: You |
| | | | must consider your manual as an important |
| If you still prefer to use frames then | | | | part of your business model. This is |
| you must use a workaround. One of the | | | | just a set of general recommendations |
| approaches is to plug a special JavaScript | | | | how to get the maximum effect out of |
| code into every page of your web site. | | | | your online help. Most of the techniques |
| The script will determine if the page is | | | | are pretty easy to implement if you use |
| showing in the frame or in the browser's | | | | good help authoring software. Apply this |
| main window. If there is no frame detected | | | | advice and make your customers feel |
| then the script will build the frame | | | | happy, increase your web site visibility, |
| structure, will load the menu pages in the | | | | attract new prospects, and generate new |
| corresponding frames and will finally | | | | sales.Dennis Crane, the author of Dr. Explain software, |
| reload the current page in the appropriate | | | | specializes in vertical markets software development. |