Tags

, ,


Preamble

(if you rate this I would like to read your comments about your rating)

Providing Help for desktop applications has been the bane of my development existence for years.  I have tried building the html help files in web editors and then hooking the content in the Microsoft Html Help Workshop: what fun…I have used RoboHelp (the old version before Adobe captured it) with mixed results and frankly found it to be a bit much for what I wanted.  Then, when I started programming in .Net I turned to nDoc for generating help files but that project died out so then I turned to SandCastle for building help files and that was a chore let me tell you (until I found SandCastle Help File Builder). So why am I droning on here?  Well, once I find a product I like I tend to stick with it (eg. I am still using the Programmers File Editor since it’s original release, over 10 years now) but I have never found a help generation solution that I liked – yet…

Maybe you have a help generation tool that you really like, perhaps not… If not, then this new post may be of some help to you.  For this review I will look at HelpSmith by Divcom Software.

Note: This review is not going to go into every feature that HelpSmith offers (there is not enough time to do that and this post would be 100 pages long) – that’s for Divcom to communicate via their website and the HelpSmith help file.  What I am going to do is create a sample help file and work with the features I would use so any ommisions are not intential they simply did not come across my radar.

Update – 08.25.2009:  Added comments from HelpSmith and corrected the topic selection dialog info.

Info on Product:

  • Current Version: 3.0 (build 9.807)
  • Platform: Windows only
  • Price: $120 (or less based on quantity)
  • Dependencies: Microsoft Html Help Workshop (direct download)
  • Trial: 30-days (enough time to make sure you want it!)

Standard Disclaimer

Let me preface this review by saying it is a review of how I see the program and how it felt working with it as well as my impressions from a software developer point of view.  This is not some indirect advertising or some way to push more business to HelpSmith.  Enough said.

Finally, here’s some links for HelpSmith:

Home

ScreenShots

Download

Online Doc

Blog

Contents

Looking Around

What I Did

Off The Top

Recommendation

Looking Around

HelpSmith is a full featured help file builder which allows you to build compiled html help (in standard winhelp and msdn style help), printable documents, and webhelp.  When I was using this program I had a sense I was working with an older style (not to say it’s old!) program akin to a VB6 style program.  That’s not a bad thing it just feels like I am working with a tool which was popular in terms of look and feel during the VB6 era.

General

Here is HelpSmith as it looks after startup (of course the size it something to be desired but it has to fit in this space!):

program_blank_startup

I really like the docking feature of the panels (I know it’s a standard thing but it’s not always done well) as it allows you to stack panels, combine them in a tabbed panel (not shown) and to autohide them (note Keywords & Styles and Formatting to the right) – makes it nice when all you want to do is just write your content.

I normally lay out my help files on paper or in an outline tool before I actually spend time to build the help file but HelpSmith really makes that unnecessary with the Topics and Table of Contents tool windows which lend a nice organizational feature when building help files.  Very nice feature.

Formatting is pretty much like basic word processing (rich text) with all the standard formatting controls including bold, italic, font types, tables and alignment to name a few.  I did try the Tables feature since I seem to see a lot of brittle implementations in the area of tables but HelpSmith’s table implementation is solid though it would be nice to see more of the table options in an optional toolbar so there would be less click navigation to find the settings I am looking for (like cell backgrounds, etc).

I liked the solidity of this program.  Plainly a great deal of work has gone into the making of HelpSmith and it shows (aside from my little pique about the programs look and feel – joking!  I’m not piqued!).

Tool Windows

Topics

The Topics tool window is where you put your project content together by adding topics to your current project.  Topics can be based on a template (I based mine on the MSDN Style template) for a consistent look and feel for each topic.  That’s a great idea because I can remember having to build style sheets and link them into my help content manually – what a pain that was!  Note the Context id’s in the default view.

topics_organizer

Table of Contents

The TOC tool window is for building that navigational feature all help files (Windows anyway) share for navigating around the help file.  This tool window is really built like an outlining tool with the option to add TOC items before, after, at the end, beginning, etc..

toc_organizer

Adding a TOC item is accomplished with the New Item dialog (shown below).  You can enter your own Title for the item or use the title of the Topic you link to.  If you know the Context id of the Topic you want to link to you can enter it or Browse for it from a list of Topics.  You can also specify the Window you want to use and the Icon to assign to the TOC Item.

toc_add_item

Here is how you browse for topics mentioned above.  One thing I would like to see changed is to show the Title and the Context Id or just the title – titles are easier to remember than id numbers. Update:  HelpSmith provided me with this Browse for topics dialog with the Topic Names showing (you have to double click on the column dividers to expand though the columns will be expanded in the future to make it easy to do so.

browse-for-topics-dialog-box

Keywords

Keywords are used to seed your help file index which makes it easy for user’s to find common topics instead of reading the entire help file.  If you are familiar with PDF files, keywords are similar to bookmarks. This is very useful for large help files.  Adding a keyword is simple:  click on the document/key/plus icon (did I describe that enough?) and a new entry will appear in under the Keywords tree item and then you give it a name.

keywords_organizer

Modifying a keyword is where you actually hook the keyword up to a topic.  Just check the topics you want the keyword to be tied to and when the user clicks on the keyword that topic will be displayed in the help file.  If you select more than one topic then the user is presented with those topics you checked so they can pick the one they want.

keywords_add

Styles and Formatting

This tool window allows you to define and apply styles and formatting to the content within your topics similar to just about any word processor.  The nice thing here is that you can see how styles inherit from base styles (ie.. Normal is inherited by Hyperlink, Text 10, etc).

styles_organizer

Projects

Hmmm… Projects have a certain meaning for me based on my experience with Visual Studio and Visual Studio.Net.  I tend to look at projects as organizational tools but that does not appear to be the case with how HelpSmith utilizes project.

There is no screenshot for a project tool window (at least I couldn’t find one) but I really would like to be able to add one here.  While the Topics and TOC tool windows are great I would love to see a main tool window where the Topics are which says: Project and under the main project node (which would have the name of the project and, in a hierarchical fashion, the topics, toc and keywords – perhaps as a navigational tool but not necessarily replacing the other tool windows.

It would be nice to also see a New Project command, Close Project command, and Build Project command (which would build the types you have selected – ie.. Html Help, Printable Document, Web Help).  From my point of view, if you are going to offer Projects then the project should be the unifying feature.

Finally, back to what HelpSmith does provide with respect to projects.  Project offer all of the settings for your help output in terms of title, copyright, compiler location, output location, etc:

project_options

Hopefully, this is not the only feature that will be offered for Projects in the future.

What I Did

Here is a screen shot of what I put together (another simpleton sample!) with HelpSmith and some shots of the output.

Project

program_with_project

You can see (above) the topics I created and how I linked to those topics both from the page and from the TOC and I also added one keyword as you will see below just to ensure it showed up in the index.

Compiling of the project is fast and works extremely well.  In fact, I had no problems at all with any of the output types – they all worked flawlessly as far as I could tell.

Outputs

Here is the compile help file (.chm) output from the project above:

output_htmlhelp

Here is the same compiled help fie output showing the keyword I added so you have an idea of where keywords are used:

output_htmlhelp_keywords

Here is the same project compiled into web help – very slick I think – this kind of thing is what makes tools like HelpSmith worthwhile:

output_webhelp

And finally, the printed manual option output:

output_printedhelp

Off the Top

Things I liked

What I think really makes this program work for me.

I really liked how stable HelpSmith feels – it responds well and shows a lot of effort has been put into this.

I really liked the multiple outputs from a single content source – that’s way cool!

I really liked the organizational features (topics, toc, keywords).

I really liked that the HelpSmith website offered several solutions for connecting your finished help file with various development tools (ie.. C#, Delphi, etc).  These solutions are stored under the Articles section on the HelpSmith website.

Things I could like

Some things that would be cool (to me) if they existed (suggestions?) or, perhaps corrected, in ForeUI

I would like it if the installer allowed you to create a new folder from the Browser for Folder dialog – I rarely install to Program Files (most everything I review goes into a sandbox folder) – just a nitpick thing certainly no big deal. Update: from HelpSmith – “As to the installer, we are using Inno Setup for this task. It offers only two modes for the “Browser for Folder” dialog-box. Unfortunately, when you add the “New Folder” button to it, it ceases to automatically add the “HelpSmith” sub-folder to the destination path…” (read the rest in the Comments section)

I would like it if there was more of a project feel to a project (see notes above).

I would like it if the Keywords implementation was a bit better.  It would be nice if, when I add a new keyword, that a dialog pop’s up allowing me to pick the topic(s) I want to associate with the new keyword – one less step would be nice and more intuitive. Update: from HelpSmith – “We will consider how we can improve the Keyword tool for the future updates. Thanks.“

I would like it if PDF was another output option.  I know you can print your output to free PDF tools such as PDF Creator but it would be nice if I could do that from within HelpSmith. Update: from HelpSmith – “Regarding to PDF. I think it is a good idea. Despite HelpSmith does not have native support for PDF so far, we can add a button for making PDF documents with a linked PDF printer. Similarly, we can add a button for creating Word RTF documents. It will provide quick and easier access to these existing features.“

Recommendation

Here we are at the end.  Well, the end of this review anyway…

I can’t say I am in the market for a help building tool right this minute but if I where I would seriously consider HelpSmith.  The price is relatively inexpensive (especially compared to time spent hand tooling the TOC, keywords, etc…) and what I would spend on a license I could more than save with the time saving features HelpSmith offers.

Take a look at HelpSmith if you need to write help files or writing help content is your game:  I don’t think you will be disappointed once you try it.

Tab