Friday, January 08, 2010

Help & Manual Publishing Issue Suggestions

Note to readers:  I really like Help & Manual.  It is an outstanding help-authoring tool.  I have been a satisfied user since January 2002.  Their technical support is excellent.

This post is part of a technical support discussion.  I’m trying to be clear.  No offense intended!  I highly recommend Help & Manual to anyone looking for a help authoring program.


Recommended Changes

1. Explicit Notification of Topics Not In The TOC

While I now understand that the ability to have different Builds for the TOC and .xml “flavors” of a given topic is considered a feature, I suggest that is appropriate only for advanced users.  If someone’s primary job is writing documentation it’s probably useful and powerful.  But I think it is a bug for novices and occasional users like me.  The default behavior had me publishing unseen, unwanted content.  For me, this is the definition of a bug.

This is a screenshot from your homepage.


Like a word processor and thousands of pages?  Looks great!  Let’s do it!  I set up the project carefully and logically, separating content in both the TOC and the Project Files.  I now understand that I was wrong but I don’t apologize for my initial expectation.  “Like a word processor” and “Thousands of pages”, plus the fact the navigator is called “Explorer”, had me expecting that it would be impossible for the files under
to in any way influence anything in, say
It was a shock to me to realize that as far as publishing goes, there are no Topics folders.  They are meaningless for controlling content.  This is quite different from all other Windows programs I can think of that use folder organization.

Did you read the help?”  “Not much, until I had problems.  What I needed to know isn’t in there anyway: ‘Our folders are not like most every other Windows program you have ever used.’”

But previous versions worked like this too.”  “That was centuries ago in internet time.  I don’t recall.  My help projects were simpler anyway.  I probably never ran into an issue.”

While I think that the “different Builds for TOC and xml topic feature” should be disabled by default for the benefit of novices and occasional users, that is a significant change.  An acceptable temporary/permanent solution is notification to the user something like this.


A notification like this probably would have saved me many hours.  Clicking on “What does this mean?” should bring up the following.

2. Build & Folders Overview in Help

Maybe pointing to existing Help topic(s) is enough, and maybe not.  The notification of non-TOC topics may have been enough for me to figure out what was happening.

No comments: