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