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

[kyleri]

For what it's worth, I tend to use documentation the same way you do, and find reading PDF documents in general (of whatever type) to be vastly annoying.

Deeply nonscientific, but still a data point.

[cahwyguy.livejournal.com]

I think you're right that it depends on how people use documentation. Myself, I prefer to print the documentation so that I can review it offline and make notes in the margin. PDF works better for that. PDF also allows me to get more of the documentation in a chunk. When dealing with HTML (web-based) documentation, the page chunks are often too small for me, and I end up having to create multiple tags or follow links hither and yon.

The worst, however, are documents not ameniable to cutting and pasting. This often happens with older scanned DoD documentation. It makes it harder to search for things.... and there's another drawback with HTML: I can't do the search without having to wander through multiple files.

[cellio]

What I'm currently doing in my SDK documentation is delivering HTML with (linked) PDF versions of individual parts (each developer's guide). The PDF is there for printing; it sucks for online viewing, but that's why you have the HTML. My coworker was suggesting just providing PDF of the whole doc set and punting the HTML.

[dglenn.livejournal.com]

First, I'll agree that the worst is text-as-image scans -- slow to load, difficult to resize cleanly, and as you noted not amenable to copy/paste.

But I disagree about HTML and printing -- the problems you mention are consequences of particular layout- and chunking-decisions, not inherent to the medium. An HTML document can be laid out in a way that prints rather well, if not with the same level of page-layout control as with PDF. Furthermore, should the user desire to resize the document for printing, the same advantages of HTML over PDF for screen display still pertain.

This is not to say that PDF doesn't have its uses -- it is definitely The Right Tool for certain situations -- but its superiority over HTML for printing isn't a slam-dunk.

I think the too-small-chunks issue is often a result of page designers worrying more about layout than content, but I'll have to go find some of the pages that pissed me off that way again, and pay more attention to what it looks like the designers/writers were trying to do when they chose their page/chapter/chunk sizes. I could be wrong.

HTML and printing

[cellio]

I think the problem is actually browsers, not HTML. When I've printed stuff from browsers I've sometimes gotten really ugly results, including truncated images (because they just happened to land at the page break). I haven't spent a lot of time exploring who's at fault here, but I know I've seen unsatisfactory printing from both Mozilla and IE.

Re: HTML and printing

[aliza250.livejournal.com]

because they just happened to land at the page break

Widow-orphan control was in page-layout and document-editing software at least 20 years ago, but an astounding number of people who ought to know better never bother using it.

Re: HTML and printing

[cellio]

That's certainly true for layout-focused applications -- it's been there for a long time and most people punt. Handling this at the source level with HTML wouldn't be feasible because, by definition, you're providing markup, not layout -- so the browser is responsible for making reasonable things happen on printing, and not all browsers do.

[aliza250.livejournal.com]

The worst, however, are documents not ameniable to cutting and pasting.

Apparently many PDF viewers make it difficult to cut-and-paste text.

(Today I had a customer ask me for a plaintext version of a PDF list of license keys because he didn't have an easy way to extract them.)

In fact, at one point that was a selling point for PDF over other document formats - that it was non-trivial to copy the text.

[cellio]

And sometimes the support is there but obscure. It took me a while to discover with the Acrobat reader how to select the text in the first place; you have to change the cursor but that fact, and how to do it, were not at all obvious at the time.

[dglenn.livejournal.com]

Thank you thank you thank you!

[siderea]

Your cow-orker is on crack. I can't stand PDF documentation for onscreen reading.

[nancylebov.livejournal.com]

I hate hate hate pdfs--they're harder to read and harder to maneuver around in tjam html.

I'm very glad that you're offering pdf and html versions of the material.

[cellio]

I'm very glad that you're offering pdf and html versions of the material.

I'm glad that, 4+ years ago, I won the source-format argument so that we can. :-) (I'm not interested in generation that can't be automated.) We have XML source and generate both HTML and PDF from that source -- independently and automatically. We've only started generating PDF in the last year, but I saw this possibility from the beginning and made sure we planned for it.

[dsrtao]

AFAICT all competent techie people are aligned with you.

[schulman.livejournal.com]

Tautologically? :-)

[goldsquare.livejournal.com]

PDF has its strength, but since all the readers I have used are fascist and under-featured, I really don't care for it. HTML at least has decent readers.

[cellio]

One advantage of a (single) PDF document over an HTML doc set is search. You don't always have access to the server for a grep. :-) But, that said, I think the readability issues are more important, and it's reasonable to just spend some extra effort supporting search or at least providing a good index in the HTML. Web browsers are so much easier to read with than any PDF reader I've seen.

[goldsquare.livejournal.com]

For search, I use Google: "site:http://www.sitename.ext/directory path searchTerm". :-)

[cellio]

Good idea. :-)

[aliza250.livejournal.com]

1. Not all PDF viewers support text search.

2. You're comparing apples to oranges here. Ease of search is a feature of a single document over a set of documents. A bunch of data organized as a group of PDF documents is no easier to search than that same data organized as a group of HTML documents.

[cellio]

A bunch of data organized as a group of PDF documents is no easier to search than that same data organized as a group of HTML documents.

Definitely. The proposal that was under discussion was replacing my collection of HTML documents with a single (mucking huge) PDF file. (Fortunately, we're not going to do that.)

[cafemusique.livejournal.com]

While we're being all dogmatic, I'll express a preference for PDF. Love the format. And I maximize everything on my computer, so it is not convenient to have two windows simultaneously visible.

[sethg]

I'm with you and siderea. The proper way to read a PDF is on paper dammit.

[dagonell.livejournal.com]

Another vote for your side. PDF link for hardcopy where I can scribble in the margins, but online reading MUST be HTML.
-- Dagonell,
P.S. Does this count as geeking about modern software? :)

[patsmor.livejournal.com]

Dagonell: I hope so!

Here's another vote for HTML for onscreen and PDF for paper and scribbling. I purely hate when some $#)#($*#$ documenter has decided what size I like my pages, how well I can see, what happens to graphics when I scroll, and so on, without a clue about how users really use & perceive the docs. Growl.

[(Anonymous)]

I recognize myself in this remark! I size my html in terms of % so size of screen doesn't matter. I don't permit horizontal scrolling and limit the vertical scrolling as well by using tables with borders turned off. It seems few people take advantage of the dual monitor capability of some of our operating systems that present nice big displays of the help and the original view that is so terrible that help is needed. A pity with monitors so cheap. I use PDF equivalents for the scribblers because the screen size is typically somewhat less than 30 lines to allow for navigation devices. In the print version these navigation aids for page turners take up headers and footers; typically on line they reside in top and left margins and the "next" symbol scattered where ever needed--so how many ways do you slice salami? Why force people to have one or the other when it is so easy to have both. There's a little box that says "save as...." and you pick your favorite conversion. And my own scribbling is so illegible it is unspeakable. If I am working for one, it is going to take til hell freezes over for me to put scribbles on line. I quit doing that in college when I took my last secretarial job. The worst part of being a documentation specialist is failure to negotiate the comfort tolerance of the process owner for being edited. Lots of times, it is not worth the fight and it's generally not MY name on it anyway.

[(Anonymous)]

I am a documentation specialist and instructional designer. There is TONS of information out there on usability. The best place to look for a rapid solution and cheap training is the before and after examples at infomap.com. As far as I can see the only use for PDF is a mild tamper proof method, such as used in testing remote sensing satellite construction before launch, when the test procedure requires prior signed approval, is only good for x amount of time, and printed copies of PDFs are "stamped" (little bitty stamps w/ink pads) and initialed by the person doing the work, a quality assurance expert, the test director, the customer and what ever other set of "witness eyes" the test seems to call for, each in their own color and area in the margins. The marked up original is scanned into the system as a perm record, and the red lines are put into the master version to correct the procedure for the next run. Of course, then you have headers, footers and a seriously heavy duty system for annotations, red lines, comments and the like.

If you consult a human performance engineer, they have tools to watch eye movement, mouse movement, key strokes and the like to track how the user actually interacts with on line documentation. Most do appreciate context sensitive documentation requiring hard wiring to code (with somethink like Robohelp or Microsoft help files) that displays in pop up windows. If you use help for processes/procedures with Word you will get an excellent example. As they say on the X files, the answer is out there. Good luck.

[cellio]

I participated in (and conducted) user studies like you described when I was in college. We only worked with very small scopes, but it was certainly an interesting process and looked like it could produce a lot of valuable information. Sadly, no employer I've ever worked for has been willing to pay for user studies for documentation, though my current one has at least done so for some of our software.

Can you suggest articles that I should look at? I am, in particular, developing documentation for programmers, so my users are trying to design systems and write code. Others in my organization are writing documentation for end users and system administrators; I suspect there's a larger body of work for them. Of course, some issues about presentation transcend usage, but some might be specific to documentation contexts. (And I'm sure that all are sensitive to the user's degree of skill.)

[dvarin.livejournal.com]

My most recent experience with PDF documentation has been the D&D online sources, which I have to magnify to make readable, causing it to be wider than my viewer even with the viewer maximized. As for coding, I'm in the flipping camp that looks at the documentation and the code editor separately and sequentially.

I (hate)^n horizontal scrolling. HTML isn't a cure-all for that though, unless you make sure to never incorporate images bigger than about 400 pixels per dimension in the same file as text. I had to tweak my LJ settings because jerks were posting 1000-pixel-wide images diretly to some communities in my friends list and making the layout wider than my screen.

PDF versus PDA in a fight to the death

[brokengoose.livejournal.com]

On occasion, I'll stuff oft-cited documentation onto my PDA. That way, I can read it on the bus, and if I'm dealing with a poorly-designed app that ALSO insists on taking up my entire screen, I can do so. Plus, tech support habits die hard. I find it comforting to have the docs with me in case I need to show them to... someone.

This results in the same problems with PDFs that your attempts to share screen space cause. Even on my "high-resolution" Palm (320x320, I think), there's no way that the entire width of a page can be read, which means that I have to engage in both horizontal and vertical scrolling. It actually gets worse with multi-column layouts, because then I end up scrolling horizontally just a little bit each time I change the view.

Re: PDF versus PDA in a fight to the death

[cellio]

Good point. Coincidentally, one of the arguments I raised against the PDF model was: now suppose your end user is out in the field and has a hand-held device. This is not hypothetical; one of our applications is probably going to be deployed in that kind of environment, and we have a lot of UI work to rethink in order to make that possible.

[madfilkentist]

There is at least one advantage to PDF documentation: It's easy to do full-text searches.

With well-indexed documentation, of course, you shouldn't have to do that a lot.

[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.