TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: Single Source Documentation From:"Huber, Mike" <mrhuber -at- SOFTWARE -dot- ROCKWELL -dot- COM> Date:Fri, 19 Feb 1999 10:32:46 -0500
Robin Whitmore
> I've decided what docs to create, I'm just not sold on a delivery
> method. I am wondering how other Techwrlers have approached this
> situation. Do you create a PDF version of the printed manual?
> If so, do you revise the PDF to be more user-friendly on screen?
> Do you use HTML instead of PDF? If so, why?
You don't mention what kind of product you are documenting, so I'll assume software, at least in the sense of "something that you can stuff through a telephone line". Otherwise, the question becomes much simpler: if you don't have a good reason to assume the user has a functioning computer, you can't get by with online documentation.
There are so many details of product placement, customer expectations and needs, and pricing, to consider to decide between online and print.
In order to decide between PDF and HTML you need to consider two points:
1) Is the document intended to be viewed on a screen or printed? This is the most important question. PDF just isn't very good on a screen. And HTML isn't very good printed out.
2) Is your exact document layout important? PDF gives you real layout control. HTML gives the user's software suggestions.
It sounds to me like you are starting out from scratch. Otherwise, legacy documents would be a concern. PDF tends to be a good solution for legacy documents that were originally intended as paper.
Something to think about with PDF: The other day I was waiting in line at an office supply store behind a guy who was trying to return some software because it required Acrobat(the software mush have included PDF documents), which he didn't have, and it didn't say so on the box. Now, I don't know whether it was a real customer problem or not - I suspect it was an excuse - but it was a rather dramatic demonstration that PDF isn't always acceptable to some customers.
Someone else mentioned using PDF to avoid offending fans of one or another flavor of HTML. There are people who are offended by PDF. I am offended by bad PDF. I've had idiots try to use PDF dumps of manuals as a substitute for help files - that's bad PDF. I've encountered consumer-level software with manuals hundreds of pages long in PDF. That's bad PDF - printing a hundred pages on the kind of printer people tend to have at home would take a long time and cost a lot of expensive cartridge ink.
If you have to use PDF for documents that will be read on a screen, make the page size small enough that the fonts are readable without side-scrolling. Or at least use columns. Ghod, I hate side-scrolling when I'm reading. I've been pushing for redesigning our manuals with PDF in mind. We provide some manuals on paper, but we also provide PDF. Our printed manuals are on a small page, so when the user prints the PDF on 8 1/2 X 11 paper, the margins are goofy wide and there are crop marks.
Now, I have a strange affection for HTML, and I find PDF kind of icky, but I would be unlikely to recommend dumping an existing printed manual to HTML. My preference would be to reorganize the material into an HTML document with lots of links and tight chunking that uses the strengths and minimizes the weaknesses of the medium. But there is rarely time an budget for such a project, and when the material is designed and organized for paper, PDF is a reasonable way to let the user handle the printing. I don't know about your manuals, but most manuals don't make good online documents. On the other hand, if you go into the project (right from the start) with the idea that the document will be both a manual and an online thing, you could create something that would work well both ways, and HTML would provide some good output flexibility.
I would avoid making a global decision on paper/PDF/HTML. Decide on a document or document-type basis. There are some things that should be on paper, some things that work well in PDF, and some in HTML or HLP.
---
Office:
mike -dot- huber -at- software -dot- rockwell -dot- com
Home:
nax -at- execpc -dot- com
