Take the 2-minute tour ×
User Experience Stack Exchange is a question and answer site for user experience researchers and experts. It's 100% free, no registration required.

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.

share|improve this question
    
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. –  Roger Attrill 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... –  Jimmy Breck-McKye 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. –  Matt Rockwell 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. –  Matt Rockwell Jul 7 '11 at 12:50

5 Answers 5

up vote 7 down vote accepted

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.

share|improve this answer

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.

share|improve this answer
    
+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). –  Matt Rockwell Jul 7 '11 at 12:47

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.

share|improve this answer

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.

share|improve this answer

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.

share|improve this answer
    
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). –  Monica Cellio Oct 26 '11 at 15:16

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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