14

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.

5
  • So online help is out - but that doesn't mean you can't have offline help in a browser - or do you have no browser capability either. Some desktop ui toolkits provide powerful html capable components - eg based on webkit. Jul 6 '11 at 13:53
  • Out of curiosity, which product? D2H?
    – peterchen
    Jul 7 '11 at 8:39
  • What's the context? Who's doing the reading? What tech and environment will they be consuming help in? We need to know more about the parameters around the deliverable... Jul 7 '11 at 11:38
  • @Peterchen, Innovasys HelpStudio2. It stopped working on one of my Windows 7 machines for some reason, but I got it running on my laptop, so it'll have to do. Jul 7 '11 at 12:49
  • @Jbreckmckye, It's a very powerful and potentially complicated piece of software that has context sensitive help that documents how to perform some complicated step by step operations. Jul 7 '11 at 12:50
11

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.

2
  • +1 100% agreed that people don't read. We get tech support calls about things that are clearly explained in our help files. I would love to have no help, but the software is so powerful and capable of doing infinite amounts of operations, it needs a help file. We have done our best to simplify it, but it still needs the documentation (think Photoshop, Visual Studio, etc. Massive programs capable of a lot). Jul 7 '11 at 12:47
  • We've advanced our in-application help and improved user satisfaction by tightly binding information to where people need it. The help is mostly around Domain complexity, not application behaviour as UX was improved. Pretty much ditched any semblance of "Read a book about an app" approach. Taking the example of Visual Studio, developers will read semantic behaviour of an API call (their Domain) very few will read "How to Drive Visual Studio"
    – Jason A.
    Nov 4 '14 at 9:47
8

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.

4

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.

1
  • We edit Docbook XML and produce PDF, HTML files, and CHM from that, based on what each distribution needs. I think somebody here even wired it up to produce Word once to satisfy some customer requirement (maybe that was RTF). Oct 26 '11 at 15:16
3

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.

2
  • All valid points, but only in relation to some things (phone apps, young users, the impatient). In the real world of business and commerce, online documentation is needed. PDF doesn't have to suck. Most people in business don't entertain considerations like "what if somebody doesn't like Adobe?" -- It's what tool gets the job done. Also, it's a red herring to say "don't document dialogs and menus" -- nobody does that anymore -- except for giant line-of-business apps that have 1,000 commands and users who demand some reference for it.
    – user8356
    Apr 13 '20 at 0:21
  • Well, it's been a while. PDF support got better, and we don't have to rely on one company pushing other software with the only functional reader available. Still, the fixed page layout doesn't scale well to an even wider range of display formats and resolutions than we had 10 years ago. It's a stop-gap measure, no more.
    – peterchen
    Apr 16 '20 at 22:52
2

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.

0

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."

Not the answer you're looking for? Browse other questions tagged or ask your own question.