PDF Manuals: The Wrong Paradigm for an Online Experience

By Mike Hughes

Published: November 17, 2008

“If we’re giving manuals to users to read online, why do we design and write them for paper?”

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’m not down on every use of PDF files online. Campus maps, article reprints, and my aunt’s Christmas letters all work quite well as PDF files. What I want to challenge in this column is the use of PDF files for distributing user assistance online, in the form of large books.

Use the following checklist to see if I’m talking about a kind of document that is near and dear to your heart.

  • The online document includes small topics—often called covers. Sometimes, these topics, though brief, use a very large font, so they convey about the same amount of information you could present in a single heading in a traditional online document. We call this kind of topic a front cover.
  • The document comprises pages—those arbitrary boundaries that determine how much of a topic’s content a user can view at once. What is on a page depends on how much of that content fits within an 8.5 x 11-inch rectangle—even though this boundary in no way approximates either the size or the aspect ratio of a computer screen. So, topics sporadically interrupt themselves, requiring a user to manually intervene by scrolling to continue reading the same topic. We call these sudden interruptions to the reader’s flow page breaks.
  • Topics are grouped into sequentially numbered sections called chapters. The chapter numbers that appear at the tops or bottoms of all pages further reinforce their sequence. The sequencing of chapters usually corresponds to the order in which a writer expects users will need each topic—or intends users to read them.
  • Some of the pages identify themselves with Roman numerals and others with Arabic numerals as page numbers. This can prove helpful—once a user realizes Roman numerals designate topics with no useful content whatsoever—which we refer to as frontmatter.
  • When a document switches from using Roman numerals to using Arabic numerals for page numbers, it often starts counting over again from 1—while the document viewer’s Print dialog box does not. Therefore, printing a particular range of pages requires users to do math in their heads.
  • Those little page numbers seem to jump around—sometimes appearing on the right of the screen and sometimes on the left.
  • The placement of text on alternate pages also shifts left and right, with a close correlation to whether those little numbers are odd or even. On the insides of the pages of print books, gutters allow space for the binding. To online readers, gutters are simply annoying.

If this checklist identifies the characteristics of online documents you’ve experienced, you’re probably starting to see what is driving my desire to move away from PDF manuals. None of these characteristics has any logical justification in the context of finding and reading topics online. If you were creating online documentation from scratch, would you have identified any of these characteristics as requirements? If PDF manuals are the answer, what was the question?

Why Do PDF Manuals Still Abound?

“Maybe creating PDF manuals seemed like an easy transition into the scary world of online information, while still remaining grounded in the familiar skill set of conventional book design.”

The PDF manual was born when a software product manager asked, “Why am I paying good money to print documentation users don’t read, when I could instead provide the same documents electronically for them not to read?” I am sure it was not a technical communicator—wedded to the myth that users were reading the manuals—who discovered this principle of economy, but we did acquiesce too easily. Maybe creating PDF manuals seemed like an easy transition into the scary world of online information, while still remaining grounded in the familiar skill set of conventional book design. Here are some dialogues that show possible rationalizations for PDF manuals:

  • “Users want hard copy. So, we should give them hard copy.” “Too expensive” is the rationale, “Users won’t pay for hardcopy.” Then, the real truth is users don’t value hard copy.
  • “Users can search the PDF file online, then print just the relevant sections.” If that is our assumption, printing should be easier than printing a PDF file is. Users should be able to designate what they want to print by topic, not by ranges of page numbers. If a topic spills over several pages, why should the user have to figure out what pages, then do the page number math? If the last page continues onto another topic, why should a user have to waste ink on a topic that is of no interest. Once again, the PDF realities just do not match any logical requirements.
  • “Books fit a metaphor users are comfortable with.” Most users don’t use real books all that well. Why should we think they’ll suddenly get it when a book is online? The hard reality is that books are a metaphor writers know well. It has little to do with what users are comfortable with. Books are simply what writers are comfortable writing.

Replace PDF Manuals with What?

“If one of the attractions of PDF files was the ubiquity of PDF readers, what is more ubiquitous today than the browser?”

The real solution to online documentation is—and always has been—HTML and its advanced sibling XML. If one of the attractions of PDF files was the ubiquity of PDF readers, what is more ubiquitous today than the browser?

So, let’s start from scratch. What do we want users of online documentation to be able to do? Here are the tasks a reader of online documentation must be able to accomplish:

  • navigate from a single table of contents to all of the information a user needs
  • search by keyword or plain text—Search results should span the entire library of information a user might need. However, a user should also be able to limit the scope of a search. A user should be able to scan search results easily to find relevant topics.
  • read topics online—Topics should flow for easy readability within a browser and behave like other online Web experiences for users.
  • select topics or groups of topics to print

So, there are four essential requirements for online documentation:

  • easily navigable across an entire set of information
  • easily searchable across a user-designated scope
  • easily readable topics
  • easily printable by topic or topic clusters

There are many ways of meeting these requirements that get the job done better than PDF files do. Even a simple Microsoft Compiled HTML Help (CHM) file can meet most of them. Personally, I have come to favor an XML-based solution that uses DITA (Darwin Information Typing Architecture) and delivery through Eclipse, an open-source development environment. This solution lets me distribute content with the product itself—either as a Help file or on a CD-ROM—or deploy it on a Web server, letting users view it with a Web browser.

Let’s compare a user’s online experience using an example Eclipse solution with a traditional PDF experience. (Such a solution does not have to be based on Eclipse. I’m just using an example of a solution with which I’m familiar.) How well does each solution meet the requirements I’ve identified?

Easily Navigated Across the Entire Collection of Information

Figure 1 shows a documentation center that includes five major books. Using a traditional approach, each of these books might be a separate PDF file. In Eclipse, you can create each book as a plug-in, and add or remove plug-ins merely by adding or removing their folders from the Eclipse plug-in directory. In our example, each book documents a component that could be installed on a user’s system. Therefore, the documentation is complete. It includes all of the information a user might need—including documentation for multiple supported versions of some components.

Figure 1—An example documentation center

Example documentation center

Figure 2 shows how a user can easily scan the contents of all of the books in the documentation center, using the Content navigation pane on the left. A user would not be able to do this as easily if this information were in five separate PDF files. Instead, the user would have to open each file separately, then view each of the five documents’ table of contents.

Figure 2—Viewing each product’s table of contents

Viewing tables of contents

Searchable Across a User-Designated Scope

“When documents are HTML pages, a user can easily search across the entire scope of a browser-based documentation center.”

Although a user can search multiple PDF files simultaneously, the files have to be in a single folder—either on the user’s computer or on a server. This is not a convenient solution for users who are opening PDF files by clicking links on a Web site, as they need them. But when documents are HTML pages, a user can easily search across the entire scope of a browser-based documentation center.

PDF search results typically show all occurrences of the search term in the context of a sentence. This can make a list of search results quite long—especially if there are multiple occurrences of the word on a page. As Figure 3 shows, search results in Eclipse appear in the context of the topic titles, and the results are annotated with a short description of each topic—a standard DITA component.

Figure 3—Search results by topic title, annotated with short descriptions

Search results by topic title

Plus, a user can easily limit the scope of a search. Figure 4 shows how users can limit a search to just the products in their configuration. A user can also limit the scope of a search to whatever topic granularity the table of contents shows.

Figure 4—Limiting search scope to specific books

Limiting search scope

Easily Read in a Browser

“The design of the documentation reflects the way users typically look for information—in small chunks and as it’s needed rather than what’s next.”

When Help topics are HTML pages that appear in a user’s Web browser, they behave in ways the user is accustomed to online documents behaving. Gone are the artifacts that belong to printed pages—such as headers, footers, and arbitrary page breaks—which while useful in print documents, add no value online. Relevance determines how individual topics are linked rather than some predetermined sequence. In other words, the design of the documentation reflects the way users typically look for information—in small chunks and as it’s needed rather than what’s next.

Printable by Topic or Topic Cluster

“Online solutions should allow users to focus on topics, not pages.”

Perhaps the least satisfying aspect of the user experience with PDF manuals is printing a range of pages. Online solutions should allow users to focus on topics, not pages. Most navigation systems for online solutions let users print a specific topic or a cluster of topics. Figure 5 shows how a user can print an individual topic or a topic and its subtopics. The user can use the same popup menu to define ad hoc search constraints.

Figure 5—Selecting topics to print

Selecting topics to print

The capability of printing topics or subtopics in online documents gives us yet another way of accommodating users’ needs. We can visualize a user as someone who wants to print a custom book—and wants only selected topics in hard copy. Part of an information design effort should be to structure a table of contents to provide logical clusters of topics for printing.

Conclusion

“PDF manuals are hard to use, expensive to translate, and have nothing to recommend them as online solutions for meeting users’ information requirements.”

PDF manuals have outlived their usefulness. Yet they’re still hanging around like sports fans whose home-town team has moved to the West Coast. PDF manuals are hard to use, expensive to translate, and have nothing to recommend them as online solutions for meeting users’ information requirements. In Gladiator, Quintus says, “A people should know when they’ve been defeated.” Someone needs to give companies who are still producing PDF manuals a heads-up.

13 Comments

I suspect that the use of PDF documentation is not so much a considered decision as the lack of a decision.

It’s possible that there are people who think a PDF provides a superior experience. However, I think many people are probably aware that it is not the best decision. It’s simply easier—or less expensive—to make a PDF of the technical writers’ output rather than retrain or hire new staff and make the sort of organizational change necessary to produce more usable documentation.

While, in principle, I have no disagreement with the concept espoused in this article, it misses one key attribute for which I am grateful to .pdf documentation—I can store them on my hard drive or server for use when I need them. Often HTML pages disappear as manufacturers deliver new products and the old ones are rendered obsolete. With a .pdf I can store the manual and refer to it anytime. I can also embed these files in databases to have a portable reference library. The problem, as I see it, with cloud computing is that it relies on a great deal of integrity, both physical and ethical. At least with the technology we have grown used to, we can maintain the integrity of our data needs. For sure, the layout of .pdf documents could be a little more imaginative sometimes—rather than just following the original paper version—but there are some great examples of interactive .pdf documents out there.

Thanks for all.

Your points are well-taken, and I agree XML is the right direction, but I think most people would agree, and the problem is just having the staff availability and skills to get it done. You talk about DITA and Eclipse. How many managers do you think speak that language? I’ll bet not many. A useful followup to this article would be how you setup and use your DITA/Eclipse station, so that people already convinced of the problem might gain a method for addressing it. As for myself, I’m very interested in the idea of DITA-wiki hybrids, but that still seems to be a thing of myth right now.

Mike, I find this approach to Help to be completely out of date, and even dangerously lulling people into a sense of we’re pretty close. My reply

Respectfully, Keith

Reply to Keith Lang’s Comment:

Folks should follow the link to Keith Lang’s reply. He throws out a thoughtful challenge about what Help should be. I don’t disagree with your vision about where Help can go, Keith, and an important first step would be to walk away from PDF manuals. I did not mean to imply that the alternative I describe is our final stopping place.

Keith also takes a dim view of my writing: “The article is like bad help. It’s too long. It’s too dry. It has no narrative, and it’s written for the kind of people that like to read manuals. I’ll admit it, I’m one of them, but I’m aware I’m the small minority. The pictures are boring. It has no characters, story, or SEX to it. And it’s text, text, text. The lack of any comments on the article makes me question how many read the full thing.”

In case you’re the kind of readers who don’t follow links, I didn’t want you missing that. I think there is a generational thing going on here. I am 59 and somewhat buried in a literary approach to technical writing. I think it is important that my generation be open to the emerging visions that younger practitioners like Keith bring. But don’t cast us aside yet like worn out number 2 pencil stubs. Not everything online has to behave like a video game or a Facebook page. And length doesn’t have to conform to Tweet-sized nuggets. Users facing tough problems with technical products aren’t as resentful of serious documents as I think Keith suspects they are. But having been said, I will try harder to be a more engaging communicator in the future—thanks for the feedback.

Reply to Stephen: You make a very valid point. PDF files are Portable—almost as if their first name was…hey! My proposed solution is not very portable. Smaller, less book-like PDF solutions could be a very viable alternative—thanks for rounding out the perspective.

Another reason PDF manuals still abound is because they shift the cost of printing the manual onto the customer. They are apparently simpler to produce—printed books for mass-market software need to go to be printed and bound several weeks before ship date, while you can generate a PDF just hours before the CD ships. But most of all, when you distribute your manual as a PDF, it saves you from the bother of actually thinking about the way to deliver your information more effectively. It’s all online. What more do the customers want?

Thanks for your thoughtful comments on how to improve online documentation.

Hi Mike

I just want to throw in my two cents. You hardly have to convince me of the virtues of DITA and Eclipse; I am about as sold as one can be. You’ve joked about having drunk the DITA Kool-Aid and turned smurf blue; in that case, I probably am as blue as the little girl who chewed the blueberry-pie gum in Charlie and the Chocolate Factory. (Hopefully I am a more pleasant human being.)

Here is what I value about PDFs:

  • They are easy to print. Often, Web pages—and this can include IBM information centers—have tables that sprawl endlessly off to the right, which burns up ink and paper.
  • They are easy to store and use offline. I like CHM files, but they aren’t much help to my brethren running systems on AIX, Linux, Mac OS, or UNIX. And much as I love an Eclipse infocenter, sometimes it just has too big a footprint.
  • It’s very easy to extract pages and combine them into other PDFs. Or even to combine multiple PDFs. When I purchase any equipment, I look for and store the documentation in PDF format. I have one PDF file that contains all the necessary documentation for my kitchen appliances, for example

The blessing of working with DITA is that it is relatively easy to construct DITA maps to generate different outputs—PDF included. If your content is well chunked and designed, it should not require much effort to create PDFs in an automated build. Yes, they won’t have the niceties that we could have back in the days of desktop publishing, but we are not generating art books.

I very much agree that some PDF transformations use archaic conventions that seem out of touch in today’s more Web-based world. Hopefully, people will put some thought into creating XSL-FO transformations that are geared for PDF documentation that is designed to be read online. But in the interim, I think we simply are asking PDFs to serve multiple purposes, much as we often ask our slides for conference presentations to do.

Best regards, Kristen James Eberlein Advisory Information Developer, IBM Internet Security Systems Secretary, OASIS DITA Technical Committee

Yes, PDF manuals are out of date. Yes, there are better ways to present the information. However, as pointed out, these really need to be cross platform. Not making them fully accessible is just asking for trouble.

I tend to agree PDF Help files and supplementary documentation do have their place, in terms of the portability. Vendors come and go, and you are still using the same old software—that’s business reality. You can at least keep the PDF documents.

Mind you, having worked on systems that don’t have Help files, as it’s all built into the application—at least the separate Help file is easier to keep up to date. The latter kind of Help seems to fall into disrepair very quickly. Hence the integrated solution, while a great UX, is a poor model for maintenance.

But failing all the good intentions, the Help files are often an afterthought. Hence they are done on the cheap. All comes down to the cost—usually with the response “oh, just PDF the printed manual”.

I would like to thank all who have commented so far—as well as those who will continue to do so. It seems we are still looking for that optimum cross of online flexibility and the PDF file’s portability. In the meantime, I like the idea of smaller PDFs that don’t have to emulate book structures and online documents that have elegant print capabilities. As a writer, I probably can influence the former more than the latter, but as I point out in this column, we can architect our online documents for printable clusters. Thanks again for the collegial exchange of ideas.

I have always thought of PDF manuals as a delivery system for a paper manual—to save printing costs. The intention always is that the user would print all or part of the manual; never read it online.

In some cases, such as physically installing hardware, it is essential to work from a printed copy. For other cases, it could be read online or printed. Personally, I prefer to print, but then I’m old fashioned.

For the software product that I currently document, I edit the single source in MadCap Flare. This is then output to Webhelp for the online version, and to FrameMaker/PDF for the printed manual. The printed manual is supplied as hardcopy to new users, as well as a PDF on the disk.

Why not take this one step further? Why not have your manual in chunks, completely searchable, within the product itself, on YouTube as text, PDF, video, XML, RSS feed, popup, widget?

If not, we will say the same in two years: “HTML and XML documentation has had its time.”

Organize your manual/documentation in chunks in your CMS and publish in several formats: RSS, XML, PDF.

Then create some small and fast-to-create tutorial videos—for example, in Adobe Captivate—and publish these to your Web site with YouTube.

Make your documentation indexable by Google, and you offer your customer the possibility to get answers as he or she wants to.

Or even better, make your customers create your documentation by adding a forum option to every page/chunk of documentation.

Low costs and massive exposure—and get more traffic to your Web site. Your marketing department will like that.

Join the Discussion

Asterisks (*) indicate required information.