Why do we need PDFs?

by Tom Johnson on Feb 5, 2015
categories: technical-writing

I've never been a fan of PDFs, but PDF output is usually a requirement someone invariably brings up for documentation. In some cases, often for unstated reasons, users will ask for a PDF, and product managers expect technical writers to deliver one.

When I get these requests, I usually create a zip file of the website and send it to the user, instructing the user to click the index file to launch it. This works well for these two situations:

• Permissions restriction situations. When the user can't access the doc site due to file permission restrictions (e.g., the user is a prospect and not a fully-privileged customer, but the sales team wants to give the prospect a preview of the documentation so the customer understands the level of technical detail involved in implementing the product), the zipped website works well.
• Offline situations. When the user is offline (for example, the user may be preparing to travel, or the user may be going on a plane or ocean cruise or remote region of the world where online access is spotty), the zipped website works well.

In both of these situations, having a copy of the website locally on the user's machines fulfills the need of a PDF.

One exception

There is one situation, however, where the user asks for a PDF not based on either of the above conditions. Suppose the website content is scattered and hard to follow. By getting the content in a PDF, which follows a linear format, the user can start the content from the beginning -- like a book -- and move forward in a sequential, logical way.

There's a lot of merit to this need. Sometimes, on a website, you put the most-searched-for information up front and bury the beginner details elsewhere.

We all know how frustrating it is to bounce around from page to page, getting pieces of information that relate to a problem you're having but not the whole picture.

By requesting a PDF, maybe the user is really asking for a book-like approach to the help content, where you allow users to see the whole at a glance, with specific chapters that build sequentially and logically.

Knowing the reason why people request PDF is important, which is why when someone asks me for a PDF, I ask them why they need it. If the reasons relate to permissions or offline access, then the zip file is fine. If the user wants a PDF for the third reason, then this points out to a poor organization with the online experience.

If you need to carve out a path for a beginner track, hello world tutorial, first-timer FAQs, and so on, then you should fix the problem with the online source rather than resorting to PDF. In other words, the PDF doesn't fix the real problem, so if you get PDF requests for this reason, you should not use PDF as a bandaid for an information architecture problem.

Reasons to avoid PDF

Here are several other reasons why I try to avoid PDFs:

PDFs go out of date quickly. People who print a PDF, especially long PDFs, tend to hold on to them, sometimes even binding them and adding book-like covers. In agile software shops, the last thing you want to find out is that your users are following documentation that was current two releases ago. In a DocOps model, you're pushing new information out regularly to respond to support issues and other changes. If customers are following old instructions, the number of support issues may even increase as a result of the PDF documentation.

PDFs look intimidating if they are long. Have you ever given someone a 200-page PDF and looked at their response? It's about the same response when you're doing your taxes and you see that the instruction booklet is 40+ pages long -- except with a 200-pager, it's even worse. The user might think, Geez, is the software so complicated I have to read War and Peace to figure it out? No thanks.

PDFs don't leverage any web display tools. Suppose your website has some navigation tabs to let users choose among code samples for several languages. Or suppose you have some interactive widget that involves dragging components into a specfic order. Or maybe you have a 30-second looping video leveraging HTML5 controls in the browser. Or you have a responsive website that looks great on mobile and tablets. Or you have a button users can click to try something out (such as an online code editor that runs code). Well, when you convert to PDF, these web design elements don't translate, so you have to figure out how to accommodate them in some other paradigm. It's not worth the hassle, given that the PDF is read by so few people.

Given all of these problems with PDF, I'm not sure why the format has stuck around for so long. I'm not even sure what the real use cases are for a PDF.

PDFs and Jekyll

One reason I'm thinking about PDFs is because I'm trying to satisfy all documentation requirements with Jekyll. You'd think that Jekyll, being a static site generator, wouldn't pose any issues for viewers who want an offline experience.

Unfortunately, you can only view a Jekyll site on a server. The server can be local, which is how you view the Jekyll site while you're building it. (Jekyll actually builds a previewable server at an address such as http://127.0.0.1:4001/.) But you can't simply open the generated files in your browser without the server because the paths aren't structured that way.

It's no problem, though. If you need to send the website as a zip file to a user, just use a tool such as Sitesucker to download the website locally. (There some alternatives as well as PC utilities such as HTTrack that do the same thing.)

Here's an example of jekyll prototype site zipped up. This is the same site that is online at idratherbewriting.com/jekyll.

(BTW, the Sitesucker trick only works with websites that are file-based. It won't slurp an entire database site (such as one built on WordPress) because database sites construct pages dynamically when a request comes in.)

If you absolutely must deliver a PDF from a Jekyll site, you could create a page that runs a for loop through all the pages, and then convert that page to PDF using a tool such as Prince XML or Weasyprint, but this will require some customization of the CSS based on your specific elements. This method will allow you to deliver a partial of your site, with assets that might not be included in the regular site. Still, it would require some setup.

Why PDF

I'm interested to learn reasons why people are delivering PDFs. If you're creating PDFs for customers, can you tell me why (other than "it's a requirement" or "customers request it")? I know that some tech pubs shops create PDFs simply because their help authoring tool doesn't have good online output. But this seems more of a tools problem than a user-requested need.

---

For another point of view about PDF, see "No PDF for you!" The destructive power of arrogant thinking, by Alan Pringle.