May 062011
 

One of the pains of developing software is creating documentation for the product. There becomes a lot to think about, which includes just letting the end-user figure it out on their own and not even bother.

Some of the things to consider for a software product:

  • Do you need a Help File for installed EXE’s?
  • Do you need a Product Manual?  Printed or Electronic format? How about a manual which could be referred from a Nook or Kindle?
  • Do you want or prefer help to be viewed via a web browser with the help stored locally or on your web server?
  • If you’re writing development products, do you need to have the file be compatible to install into Visual Studio or Embarcadero’s Delphi or C++ Builder? IDEs?

Uggh…..  sounds like there’s going to be a lot of writing. And using several tools.  Get Word out to write the manual for the printer. Get a tool to make a help file. Get Dreamweaver out to make the web pages. I think it’s time to go back to just writing the program and not even bother.

Well EC Software has a great product that puts everything into one tool called Help and Manual. The product takes the write once, output in many ways approach which lowers the overall time needed to create your help file, printed manual and online help file and allow output for the needed formats to be generated in a single click.

Installation of the program is easy by downloading their installer from their website. The code-signed installer is simple and typical of installing most programs. EC Software also offers a Premium Pack set of templates that are in a separate installer available as an optional add-on.

Help and Manual uses the Microsoft toolbar / menu system design introduced in Office 2007, making navigation and use of the program easier to learn.  There are several example projects installed to help learn the product and see the capabilities.

When setting up a project, you make use of the project explorer and create book chapters and topics. Within each topic page created, you can enter your text, then use the Topic Options for the page to enter keywords that would be used to index the help file as well as become part of the index used in the printed documentation. Other options include configuring help context IDs for context sensitive help.

A unique feature is having access to the topic text as XML, allowing finer grain presentation of the topic page.

Help and Manual offers use of text variables within the text and project. For example, if your new software product was called Widget 2011, then create a text variable called PROGRAMNAME and then use %PROGRAMNAME% anywhere in the topic text to automatically fill when generating output.

The editor for the program is easy to use and contains the typical text formatting features expected for word processing. The software also includes a spell checker, of which several language dictionaries are available.

Need to earmark a topic page as pending, while you’re working on it? Not a problem. If the project is generated, it will ignore those topics.

When creating PDF / printed documentation, Help and Manual provides a template design tool, allowing you the freedom to design how the cover would look, table of contents and index appearances and the content pages. If you like your page numbers to be at the top of the page, simply use the design tool to move the page numbers to the desired location. If you prefer to show your Index in two columns, but want your table of contents to be one column, it’s not a problem.

Help and Manual offers its own screen capture utility to make it easy to take a screen shot of your program, manipulate the size, such as shrink it 50%, then save it as a PNG or other format. I personally love Snaggit for screen captures and H&M’s utility doesn’t attempt to outshine or outperform. But it’s included and realistically perfect for most jobs. H&M also includes an image editor to add callouts or other embellishments to the screenshots.

What if you have a bunch of chapters or topics that you don’t want to waste pages for the printed manual, but you want to include in the help file or web based help? Not a problem with Help and Manual. Topics can be flagged to be used for specific or all output types. If you have a couple paragraphs of text that would be best left out of print as well, you can use a conditional flag around the text to accomplish the same goal.

There is a lot of control offered for output destinations. The PDF output allows for generating an interactive document or as a simple document. The prior allows chapters and “See Other” links within the document to jump within the PDF. Security can be applied to the PDF to prevent printing or modification and fonts can be embedded or not.

Generating Winhelp (the help system used in older windows) and HTML help (used mostly now for program EXE’s) will require installation of Microsoft’s help SDK’s which must be downloaded separately.

One of the more recent features of Help and Manual has been the support for multi-user editing.  If you have multiple technical writers and require editing the same help file, you can easily edit the file and see when a topic is currently being edited by someone else.

Help and Manual supports Unicode fully, allowing integration with tools used to support multiple language translations.

The output can be generated via command line automation, making it easy to include generating documentation as part of the build process.  For those using FinalBuilder (one of my favorite tools that was introduced to me by Nick Hodges), there is built-in support for automating the building of the H&M project.

One of the newer features I like is the ability to collapse text using toggles. This is seen a lot in websites that use FAQ’s and don’t want to overload the viewer with both the questions and answers run together.

There is certainly a lot more to the program than what’s been mentioned. Help and Manual is reasonably priced for all it offers. Especially when comparing to some of the other commercial tools such as Robohelp.  The software has a standard and professional edition along with a concurrent license for larger license needs.

If you are a developer working on open source projects, contact EC Software to find out about their requirements to acquire a license of Help and Manual for little to no charge.  The company has been mentioned in credits for projects, such as GExperts, as providing a free license for the project.

I strongly encourage readers to check out the demo at helpandmanual.com and see for yourself.