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.
| We've used Frame -> pdf for single-source docs for some time now and
| have had favorable comments from customers about the practice. Except
| for re-flowing the text to fit a browser, Acrobat can produce all the
| links, bells and whistles HTML can, IMHO (although I'm told my opinion
| is limited).
Not exactly. You can't compile PDF into a WinHelp or HTML Help file and link
it to a software application, for example. Another example: downloading a
3MB PDF from a server that's not set up for byte-serving can take a real
long time--much longer than downloading a single HTML page.
| The basic problems with HTML are that, as good as Webworks output is
| (and it's pretty good), there's at least another edit cycle to check the
| output to see it's not garbled somehow.
We use WebWorks Publisher all the time, and we *never* do *any* tweaking of
the HTML output. If you're tweaking the output from WWP, it's because you
haven't set up the conversion template to do everything you want.
| Also, you must mark certain
| things as "print only" with conditional text (e.g. the "Conventions in
| this manual" section that explains font use, or graphics you do not want
| to see in the HTML output). Webworks will exclude the conditional text
| settings you configure. Maintaining this difference between print and
| online is not part of the pdf output, but must be part of the HTML doc
| production.
And this is one of the great benefits of using WWP: you can flag elements
for inclusion in particular media and exclusion from others. It's entirely
appropriate to have some information in print, for example, that may not
appear online, and vice versa. No tool I'm aware of makes this easier than
WebWorks Publisher.
| Many experienced folks say you must maintain two versions: online and
| print. I don't disagree--the maintenance of a single version with the
| conditional text is that much work. For example, if you have a
| cross-reference to a conditional text passage, you must write so that
| cross-reference can be omitted (and make the cross-reference itself
| conditional). This is a task that can expand exponentially...
Why would you want to do this? FrameMaker XREFs end up as hypertext links in
the generated HTML, which in most cases is highly desirable. It's quite easy
to set up WWP to convert print-style XREFs like "For more information, see
'Configuration Options' on page 4-16" to online-style XREFs like "For more
information, see Configuration Options."
| The downside of pdfs is that they can't be "What's this" or
| context-sensitive help. IMHO (again) context-sensitivy is almost always
| useless, (besides being a maintenance nightmare) and if needed, bespeaks
| a need to redesign whatever it's explaining more than it provides useful
| information. Try getting context-sensitive help the next time you use a
| spreadsheet. If you want to know about formulas, it'll tell you about
| formatting...etc.
You may find context-sensitive help useless, and I won't dispute that many
times it is rather poorly designed and implemented. However, it's also a
requirement for most commercial Windows applications and for many corporate
apps, as well.
