PDF isn't the right way to deliver help

James Robertson points to an aspect of one of my minor peeves with software: manuals that are online PDF's.  PDF manuals: the wrong paradigm for an online experience

Mike Hughes writes about the problems with PDF manuals. To quote:

Let me describe a familiar user assistance experience. A user installs a new application, and when the user wants Help, the application directs her to the user documentation on a Web site or CD-ROM. What the user finds there is a PDF file containing the manual—or a collection of PDF files, representing a library of manuals, including a user guide, configuration guide, troubleshooting guide, and various references. And the layout of each of these PDF manuals is exactly the same as if it were a printed book. This raises an interesting question: If we’re giving manuals to users to read online, why do we design and write them for paper?

I hadn't even thought of this aspect of usability, but I have to agree. 

My beef is usually that I need help precisely when I am in the middle of something and don't have the time (or connection) to go off and download a bulky PDF file.  Why can't they have context-sensitive help or otherwise useful information, such as context-setting scenarios?  Even better, why not make the application clear enough to use that I don't need to go traipsing off to the manual? 

The full Mike Hughes article goes into some detail on this topic, even providing some pointers on how to provide useful (online) documentation.  One thing I'm happy my current employer does with their software is that all help is delivered with the software in the form of traditional F1-access help files.

3 Comment(s)

Bud Gibson said:

I agree that application integrated help is the best. PDF based help is not particularly effective, very akin to searching through a manual.

I would say that after app integrated help, web based help is often serviceable and may benefit from social features.

Michael Jahn said:

Hi there,

Where to start - as a consultant who has helped vendors launch products, I will say that - in general - a lot more effort is put into marketing web sites and brochures than the knowledge base and help files.

So, let me just share that I guess people should be happy that they get PDF manuals at all !

Seriously, there are great tools available for software developers to make help files - I happen to use Help and Manual


You can build a help file using these tools, then export them as a word file, a PDF file, or a set of HTML pages - as well as an application help file that can be accessed via a help manual while the application is running.

It is not that PDF is inappropriate as a help file format. It sure beats nothing - you can print it an search for text strings and (if they built it properly) the TOC (Table Of Contents) will have links to chapters, figures and the Glossary.

The real problem is that it takes a lot of build all the things that people need to learn how to use an application - besides version release notes, a knowledge base, tips and tricks - a user group and user forum (where users can ask for help) - sometimes a user manual is ideal as a PDF, other times - it is pop up balloons help files inside the application.

Michael Jahn
Jahn & Associates
PDF Color Conversion Specialist
1824 North Garvin Avenue
Simi Valley
California 93065
Office: (805) 527 8130
Cell: (805) 217 6741
Email: michaelejahn@gmail.com
Skype: michaelejahn
Twitter: http://twitter.com/michaelejahn

Teramis Author Profile Page said:

Thanks for this commentary, Jack. You say this is a minor peeve of yours regarding software; it's a major peeve of mine regarding the persistance of analog thinking in a digital environment.

I think we (we in the collective, as a culture) are entirely too slow to really think through the implications of the technologies we're working with. That documents are ported to pdf - the rockin' new technology of the 1990s! -made sense in its day, but busines adopters, used to thinking in a paper paradigm, were often just marginally comfortable pushing the envelope into the wild beyond of the electronic paper paradigm. They've hardly gotten beyond that point today, but I think the accelerated rate of technological change is going to compel much broader change, no doubt much sooner than many old school thinkers are comfortable with.

I wrote something in this vein at my website, and referenced your post in it. You can view it here: http://www.deborahteramischristian.com/processes/analog-thinking/. I welcome your comments if you care to share any.


Deborah Teramis Christian
Novelist, sociologist, and former systems consultant

Leave a comment

Previous entry: Happy Thanksgiving

Next entry: Collaboration, or walk before you run

Picture a steaming coffee cup. Better yet, grab one and have a read!

KJolt Memberships

Follow jackvinson on Twitter

View Jack Vinson's profile on LinkedIn