documentation: the assumptions behind presentation

[cellio]

A coworker and I had one of those mutual "you believe what?!" moments, and it was surprisingly educational and non-heated. Nifty.

We were talking about documentation that's meant to be viewed online. My favored format there is HTML; he was advocating PDF. And when we had peeled away the surface issues, it turned out that our user models are fundamentally different.

To me, online documentation is all about the content, not the page layout. I find chunks of whitespace before the next page distracting (wasteful of my valuable screen real-estage). Ditto running headers and footers; they don't run in my viewer but rather on the page whose size probably doesn't match that viewer, so what good are they to me? (Obviously if I print the doc that's different.) And a PDF viewer, being page-centric, does not afford me the convenience of resizing and getting a fresh layout. The viewer does not flow the content to me in useful ways, so it is a hinderance.

In a web browser with HTML, if I change the font size the content re-renders to fit in the window; I don't get a horizontal scroll bar. Not necessarily so with PDF; if I try to make the font too big for the allotted window, I have to scroll sideways to read -- which is enough of a PITA that I might then just print the sucker even though I wanted to read it online. A common response to this -- and my coworker's assumption -- is that people will maximize the viewer window and that will be (1) good enough to avoid this problem and (2) worth it for aesthetically-pleasing layout.

No, no, no! Yes, if I maximize the window then most normal PDF documents will be readable for me without scroll bars, but that is not the point. Why on earth would I maximize the window? And why should I impose this burden on my users?

For some reading, sure, this makes sense. But if I am consulting the documentation for an application I'm trying to run, I want to see that documentation and my application window at the same time. I might need to compare what I'm seeing in the app with what's in the screen shot in the doc. And if I'm writing code while referring to some SDK documentation, you can bet that I want to see my code next to their example code or API specification. Flipping back and forth forces me to allocate more memory, and I have better uses for those brain cells. If doc presentation hinders the user, the presentation has to change.

My coworker, on the other hand, is used to toggling. And he just plain reads enough online (that is, reads without simultaneously doing) that giving over the entire screen to a reader makes sense. It never occurred to him that people use documentation the way I do. When we began the conversation he was pretty sure I was a mutant due to my vision issues, but by the end he saw that normal people have these issues sometimes too, and he agreed to go off and think about what this means for our formatting templates. It was a productive conversation -- and that without either of us realizing the disconnect in advance and thus preparing diplomatic turns of phrase. :-)

Of course, it would be nice if we had some actual user data for our documentation. That's remarkably hard to get. I can observe our developers using my SDK documentation (and I do), but they're not necessarily represenative either, nor are they at all representative of end users. Actual customers, however, are notoriously bad at responding to surveys, and controlled user studies are expensive.

Comments

[lensedqso.livejournal.com]

Most places I've worked put API and other reference docs in HTML (sometimes only offered online) and conceptual/procedural docs in PDF or HTML and PDF. I personally prefer everything in HTML for some of the reasons you state plus several others (fuzziness of PDF text onscreen, ability to link to specific items from within the product are two).

One of the places I worked did a user survey on this subject and found that the preference was almost 50-50 (this was 6-7 years ago and not a large enough sampling for any type of statistical accuracy) and that most people had a strong opinion. However, when we split out reference material from other docs, even the folks who wanted PDF saw the benefits of HTML.

[cellio]

Fortunately, no one has proposed putting the pure-reference part of the API documentation -- that is, the javadoc -- into PDF. That would suck. :-)

My doc set contains developer guides (conceptual material plus key entry points into the API), a quick-start guide (very procedural, for people too lazy to read documentation first), extensive documented examples (text includes key code excerpts; full source code is linked), instructions for running the apps in the suite, the javadoc, and the usual extras (high-level overview, glossary, index). One big PDF file for everything minus javadoc would I think be unwieldy (it would be about 600 pages if you didn't include the full source for the examples).

By the way, I also brought up your two arguments against PDF. Internal linking has gotten much better recently (though I don't know about linking from outside), and my coworker showed me non-fuzzy PDF that convinced me that with proper configuration and good font choices that can be dealt with.

One tidbit I didn't know: generating PDF, at least using XSLTProc, involves loading your entire source into memory. It can't stream. I had always assumed that a file-transformation process would be disk-bound, not memory-bound. A coworker reported builds (from a previous job) that took hours to complete. Building the PDF for the individual developer guides and examples takes about five minutes.