Which type of help system is best?

Question

At my company we create Windows based desktop applications. In the past, we have created .chm files for our help documentation and have been happy with it. We have now been faced with some issues regarding the software we use to create the .chm and would essentially have to invest a lot of money to continue using this .chm creation software, which leads me to this question: Are .chm files the really the best avenue for providing help documentation?

I have done some research on creating PDFs with all of the elements that are in the .chm files such as a table of contents and links that jump to other sections in the document. Online help is not an option. Whatever solution we pick has to work without an internet connection.

So again, which type of help system is best? Are PDFs acceptable instead of .chm files? Is there another better alternative?

Update: It looks like we have to use .chm for a few reasons, mainly because of its ease of updating and distributing (only 1 file). My runner up to this would have been html help, which is essentially what a .chm is anyway.

Answer 1

People don't read. The best help is no help. Of course to do that, you need to put a ton of time and work into the UX.

So, assuming you do need help, I'd suggest the best would be context sensitive help that can link to your web site with the latest up-to-date help information. You'd publish help as HTML, saving you from proprietary CHM production workflows.

Answer 2

As others said, you should look into generating HTML files that you ship with your product for help. One of our products (used in an environment without internet access) has been doing this for years and many users prefer it to the PDFs we also ship because the navigation is easier, the content lays itself out to fit the browser window, and the chunk size is smaller. Our HTML configuration also supports context-sensitive help, though we haven't implemented that yet.

A PDF is a nice presentation of page-based documentation, but if the user wants to avoid horizontal scrolling in order to read it he has to allocate a fair bit of screen real-estate. Depending on his monitor size(s) and the space needed by your application, it may not be possible for him to view the help alongside the application, which is a hinderance if he's using the doc to walk through a step-by-step procedure.

As implied in my first paragraph, generating multiple formats is not hard if you have the right tools. No reason you can't generate and ship both HTML and PDF, giving the user the option.

Answer 3

For automatic generation of technical documentation you can use XML publishing formats such as Docbook or DITA. In particular, DITA is capable of generating PDF, CHM, RTF, and HTML.

I have used the Serna Free editor which provides good visual editing support (WYSIWYG) for DITA in order to reduce the XML specifics.

However, technical documentation is not the most effective manner to communicate to end-users. Increasingly, interactive protoypes are used to communicate with users. For an example, take a look at the Google+ demo. Elaborating this kind prototypes can be expensive. However, if a UXD process is used, those prototypes can be used at many stages of the process. So they may be worth the effort.

Answer 4

PDF is a bad option:

• it's page oriented, which sucks for on-screen reading. PDF makes you choose between unreadably small and lots of scrolling.
• Search is terribly slow to handle in comparison to anything else
• Some people react strongly negative to some products associated with PDF. Imagine an Aggrobat hater in acompany with a very strict IT policy
• PDF is a print format, not a read format

If it has to be PDF

• landscape format for pages
• Use a generator that creates an index
• Bundle a decent PDF reader with your application (Install optional, of course)

How do you author help?

I'd go for tech writers editing HTML directly. Sharepoint Designer is free and "works just like Word" (actual quote), you'd need some setup and rules regarding styles, cross-linking etc., but it worked out.

Whether you bundle the HTML in a CHM doesn't really matter much. The main advantage of CHM over plain HTML is the Index and Full Text Search. There are some client site HTML search engines but I haven found one that's easy to use

Content over format, write for todays users

Even though I've bashed PDF above, I'd still claim content is more important than the final wrapper. A great manual in PDF beats a mediocre one that can be downloaded directly to brain.

User behavior has changed significantly with the advances of UI

• Users expect they don't need to read you manual. If your software requries reading a manual, your software sucks. (There's seems a remaining <1% of users who do read cover to cover and will point out incorrect screenshots and minor spelling mistakes)
• Users will turn to your manual when they are stuck
• Users will turn to search, and will try different search terms / search incrementally.

There's not much point in documenting dialogs and long lists of menu items anymore. Provide a task-oriented manual, lots of How-To's and sample scenarios. Answer questions. Don't describe dialog elements (they should be self-descriptive), but how they interact with others and affect the result.

Use the interactive features of HTML. You can embed videos, audio, link to your product page etc.

Answer 5

A key question you have to answer is whether you want to offer separated help or a context-sensitive help mechanism. One, t'other or both will probably affect your choice of tool.

Regardless of what you think of them, Adobe generally have pretty good help mechanisms within their application. From what I can see, they're bespoke alternatives to CHM, but seem to be HTML based. I haven't the latest versions of their stuff, so I'm not sure how they do it now.

As Roger says, there are tools out there which allow you to generate run-in-browser HTML help systems. But again, the usefulness of these may depend on how context sensitive you need your help to be.

Answer 6

Depending on the application, more or less online help can be extremely useful. Some forms are better than others. Some are easier to produce, or maintain.

Often, there's a requirement for there to be a user guide, which then drives the main documentation effort. Then online Help can wind up as a re-purposed or derived form of a book-like guide -- even if the guide is never printed but only exists as PDF.

These efforts can be OK or lousy. Simply slapping a PDF up on screen is not great. You have to put some work into (re-)organization, bookmarking, hyperlinking, searchability of the user's guide to make it useful in the program.

You have to choose your delivery format based on audience, attention span, need for printed materials. Internal business applications call for training classes, which can also drive demand for a book or other training deliverable.

If your application can get by without explaining anything or showing any additional help for users while they're using it, hooray, the developers hit the jackpot and probably had a team of writers and tech communicators working alongside them.

That's almost never the case. Almost all software needs to display, in-app, some "how do I" and "how does this tool work" Help topics. These days, the easiest ways are CHM (compiled) Help and HTML-based help, with interactivity delivered through Javascript. You can have an HTML Help system that's identical to CHM by using one of the expensive Help development environments or using free editors. I had a lot of success with a library, FAR Help compiler, a kind of combined CHM / Javascript workshop that is nearly free.

I'm become convinced that HTML5 is the way to go for any online documentation/Help system. With Javascript, CSS, SVG graphics, many libraries, you can deliver all the interactivity of any website and include animations, videos, full-text search, AI, 3D, and more.

There is no perfect development environment for all that, because it requires writing and language tools that code editors alone don't have. There are big publishing packages that promise multiple output formats, but its impossible to be perfect at too PDF, CHM, HTML authoring and output.

Visual Studio along with a content-management database and word processor (probably Word) would be one set of tools for dynamic HTML 5 Help systems. So Would Flare or FrameMaker. You still likely need a web editor (MS Expressions Web, Dreamweaver, etc.) for times when you have to work directly in the HTML. You need Photoshop or other image editor, and a versatile capture tool.

Most importantly, if you want excellent online help, you need experienced technical writers, who are really interactive documentation developers and communication specialists and much as they are "writers."