Make Documenting Your Software Easier Than Ever Before

by: Daniel Punch

Here at M6.Net we've just released our new control panel software, allowing for easier and better control over our clients' website accounts. It was my task to write the documentation for this new software. After working through it in a traditional word processor application and subsequently producing a final product that was of little use, we came to realize that there needed to be a better way to write a manual, and to release it in multiple formats. One of the lead developers sent a link my way and after trying the evaluation copy of the software I realized that it was the package that we needed. 'Help and Manual 4' turns manual writing and distribution into a very simple affair. The Help and Manual (hereafter known as H&M) homepage (http://www.helpandmanual.com/) states that "Help & Manual makes producing help a pleasure" and this is a fairly accurate little catchphrase. When I first tried the evaluation version or edition 3 a while ago, it frustrated me that I had to copy and paste every page of the manual from the word processor into H&M. This was a daunting task even for our modest sized manual that runs just over 50 pages. With the newer version however, all I had to do was export the document to Rich Text Format and use the import feature in H&M. The software went off and did its thing, returning to me with a nice manual file broken into sections based on the various headings in the document. While there were a few minor layout glitches these were easily solved, and the overall benefit of being able to directly import the manual was a huge timesaver. While it took me 3 shifts (about 4 hours a piece) to import and format the manual manually, with the new version of H&M, I had it all looking and working nicely within a single shift and still had time to edit and modify the document. The second feature that impressed me greatly was the sheer number of output formats available to the manual writer. The formats include HTML Help, Classic Winhelp, VStudio help, Browser based help (HTML pages), Adobe PDF, MSWord manual and eBook. There's bound to be an option or two that are right for your manual. For us it was perfect. We could create an HTML file for online help, and a downloadable PDF version of the document for offline perusal. Each output style is fully customizable, particularly the document outputs which can be modified with a handy tool called the "Print Manual Designer". This comes included with H&M and allows you to design the overall look of your manual in an easy and self-affirming way. I've spent a while talking about the input and output options, but not the functionality. I'm pleased to say that the interface is straight forward and all the expected options (or at least all the options that I expected) are included. You control the layout in a tree structure on the left hand side of the screen. This determines the numbering of your sections in the final exported manual. Then there are the many standard formatting options like font attributes, tables, character insertion, image insertion etc, but there are also more unique media options. It's possible to embed movie, sound, flash, and other files straight into your manual. This allows you to make a demonstration video illustrating the point the manual is trying to make and include it as part of the documentation. Obviously the viability of this depends upon your chosen output format. There are a few unique tools that I thought were exceptional concepts. The first is the Syntax Highlighter that allows you to highlight code in your manual to look much the same as code in a development environment. I didn't actually have reason to use it and test it, but I think the idea is a great one. The second is the Screen Capture tool. This useful little gadget hides the H&M window and allows you to capture an image of any control or window in an open program by simply holding the Ctrl key and then clicking the window. This image is saved into your images folder and inserted into the manual. It's quick and easy to use and saves a lot of time when compared to the alternative method (opening the program, hitting print screen, cropping the image to a desired size, and importing it into the H&M software). Overall I was very impressed with 'Help and Manual 4'. Beyond being a basic conversion tool, it makes it very easy to write your entire manual using just the functionality of the software. Once your information is all inputted there are many customization and layout options to get it looking just how you want it. When you're done you can output it to many different formats. Help and Manual made writing and distributing our manual quick and easy. Check it out at http://www.helpandmanual.com Pros: - Excellent output options - Comprehensive formatting tools allow complete control of a project's look. - Screen capture tool - Good import options Cons: - There can be some formatting errors when importing from a document. - You can't select a network folder for your images folder. It is limited to your local hard drive(s). Score: 4/5 About the author: Daniel Punch M6.Net Web Helper http://www.m6.net Circulated by Bandoni Media