RE: Single Sourcing

Subject: RE: Single Sourcing
From: "David Knopf" <david -at- knopf -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 25 Feb 2002 12:54:00 -0800

Paul Hanson wrote:

| I disagree that conditional text is a requirement for single-sourcing.

It is a requirement, generally acknowledged by vendors and implementers
of true single source solutions. Actually, I think you make the case for
it yourself in your post.

| I
| disagree that you cannot use a RoboHELP project to create a printed
| manual.

I don't know who suggested that you can't do this, but I agree with you.
It is certainly possible to generate a printed document from source
files created in RoboHelp. That doesn't mean it's single sourcing,

| Like Jessica Nealon, creating a printed manual from RH is a
requirement of
| my job. I had to find a way to do it.

And you are to be commended for the solution you've created, which I'm
quite familiar with from your detailed posts here and on other lists.
You've done a *great* job of meeting your employer's requirement, which
of course is more important than the technical question of whether
you've implemented a true single source workflow. That said ...

<snip detailed description of Paul's process>

| As far as writing style, I write generically. I don't mention page
| numbers.
| I don't mention anything specific to print or online formats.I refer
| sections that will be hyperlinked to in online and a cue to go to the
| in
| the printed doc. I don't write "Refer to the section on the next page"
| "Refer to page 72". Write "Refer to Gadget Maintenance section for
| information" where "Gadget Maintenance" is a hyperlink in online and a
| entry in the manual. To break up big topics, I use mid-topic IDs in
| Heading
| 3 style that show up in my TOC.

It seems to me there is a lot of compromise here. You are forced to omit
from your printed documents elements that are standard in printed
documents (cross-references, explicit page number references, and so
forth), and you are forced to "write generically" instead of writing
specifically for both the printed and online media.

-> You can't write "Refer to page 72" because your toolset and workflow
don't allow it. Instead, you have to direct the reader to flip back to
the TOC, locate the section you've identified, and then flip to the page
containing the relevant, cross-referenced information. While this may be
totally acceptable in your circumstances, it is a serious limitation in
a printed document. If you want to create the best possible printed
document, you say "Refer to page 72," instead of sending the reader to
flip through the TOC. Any true single source tool and workflow easily
accommodate explicit cross-references with page numbers in the printed
document, with corresponding hyperlinks (without page numbers) in the
online version.

-> You also must "write generically" because your workflow and toolset
do not permit you to create content that is specific to either the
printed or online output. While it is certainly feasible to write in
this way, it is usually not desirable if the printed and online output
are both important deliverables. A true single source workflow and
toolset easily accommodates "writing specifically." That is, you can
include content in print that is excluded from online Help, and vice
versa. For example, you might want to include some graphics in your
printed document that do not appear in your online Help; or, you might
want to include several detailed paragraphs about a particular concept
in your printed document, while presenting a more abbreviated
description online. Conditional text (to the character level) is what
makes this possible. Your toolset does not support conditional text;
therefore you must compromise by "writing generically."

In my view, compromises like these are what drive many people away from
single sourcing, and understandably so. There is no need to make these
compromises with a true single source workflow and toolset.

We don't use single sourcing for all of our projects because it's not
appropriate for all of our projects. However, when we do use single
sourcing, we are not willing to comprise the quality or usability of any
of the deliverables we produce. We insist on a maximally useful printed
document, which means, among other things, that it will include
cross-references with explicit page numbers and other content
specifically geared toward printed output; likewise, we insist on
maximally usable online Help, which means the Help will include content
and other elements that are excluded from the printed document.



David Knopf @ Knopf Online / San Francisco, CA / 415.550.8367
mailto:david -at- knopf -dot- com /

WebWorks Publisher Certified Trainer
RoboHelp MVP & Certified RoboHelp Instructor
Member, RoboHelp Community Advisory Board
Member, JavaHelp 2.0 Expert Group
Moderator, HATT & wwp-users

Now's a great time to buy RoboHelp! You'll get SnagIt screen capture
software and a $200 onsite training voucher FREE when you buy RoboHelp
Office or RoboHelp Enterprise. Hurry, this offer expires February 28, 2002.

Have you looked at the new content on TECHWR-L lately?
See and check it out.

You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.

Single Sourcing: From: Paul Hanson

Previous by Author: RE: Single-sourcing
Next by Author: RE: Single-sourcing
Previous by Thread: Single Sourcing
Next by Thread: Tracking Revs with the Naive User

What this post helpful? Share it with friends and colleagues:

Sponsored Ads