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.
| Bill Swallow wrote:
|
| > ::: So I concede Jan is right, for the most part 8^) But my point
about
| > ::: single-sourcing is reinforced. Write-once, compile-many is
| > ::: single-sourcing,
| > ::: and we both agree on that. However, if you write a block of
| > ::: text that can be
| > ::: printed as is, but is only good for the most part online,
| > ::: and has slight
| > ::: differences in a different target medium, the value of
| > ::: maintaining a single source is diminished.
| >
| > Which is where a tagged structure with conditional elements comes in
| > handy. You can, for example, author the paragraph with both online
and
| > print elements in use, and then select one element type or the other
| > when you need to publish.
| >
|
| I would argue that while you _can_, you really don't want to. And you
| especially don't want to set up such a protocol for other (lesser,
| newer) writers to follow.
|
| The downside of such an approach is that in the middle of considering
| who your audience is composed of, what it is you want to tell the
| reader, how best to phrase that, what the company style guide says
about
| the subject, and the relationship between this paragraph and the
| thoughts that precede and follow, you don't want to stop to consider
all
| of that stuff in two contexts. That's just too many balls to keep in
the
| air at one time, and productivity--not to mention mental health--has
to
| suffer.
I think you make a good point in that a writer who is not willing or not
able to keep these balls in the air is going to find it very challenging
to write a true single source document. On the other hand, I think you
significantly overestimate the difficulty of the task. I do this kind of
writing all the time, as do many dozens of writers I have worked with in
the software industry over the last few years.
I think the key point is how much overlap is there or, put another way,
how much variation is required to accommodate the various output media.
To use an extreme example, for a document in which every paragraph must
have different content for print and online, the single source approach
to writing would be overwhelmingly complex (and would offer little
pay-back anyway). For most documents that we work with (mostly software
documentation and online Help of various forms), the overlap is greater
than 80% and usually greater than 90% in terms of actual written
content.
While there is always some adjustment when a writer begins creating
single source documents, it is not usually overwhelming. In fact, with
80-90% overlapping content, it's pretty straightforward.
| Conditional elements have their uses (instructor notes, for example,
or
| platform issues). Primarily I see conditional elements as being
| dependent on the audience, not the medium.
Why? Conditional elements are routinely used to create platform-specific
content, audience-specific content, *and* media-specific content. These
are the purposes for which conditionals are intended.
| If I am writing for the
| benefit of a system administrator, it doesn't matter to me whether
that
| system administrator is reading print or online text.
Why not? There are things you would want to vary even for this audience.
To take an obvious example, your print document might say: "For more
information, see 'Configuration' on page 3-36." In your online version,
the "on page 3-36" portion should not be displayed. (Unless your online
version is simply a form of digital paper like PDF, but producing PDF is
no more an example of single sourcing than is printing the document on a
LaserJet.)
| It does matter
| that I may need to expose certain details to the administrator that
I'll
| hide for the user.
|
| So in some sense using conditional elements is a form of
single-sourcing
| (one source, multiple audiences).
Certainly. Single sourcing enables you to tailor content for a
particular product variant, a particular audience, or a particular
output medium. These are the three classic applications for single
sourcing.
| However, I think of single-sourcing more in terms of one text,
multiple
| media. And for this purpose, asking the author to handle the variants
| while writing seems inefficient. It makes much more sense to build the
| intelligence into the authoring _system_ rather than the authoring
| _person_.
Yes. We build as much of this intelligence as possible into the
authoring system itself. For example, if we determine that screenshots
within procedure steps will be included in print but excluded from
online Help, we automate that (though tagging) so that the author need
do nothing extra in preparing the documents.
A great deal of this can be automated. When it comes to the actual
writing of sentences, however, we rely on the author, but the author's
task is not so great. For example, if the author writes a sentence that
begins, "This manual describes," the author will have to remember that
manual is generally a print-only term and include an appropriate variant
for the online version. In this case the author writes, for example,
"This manual Help system describes" and applies a print-only tag to the
word "manual" and a Help only tag to the phrase "Help system." It is not
so difficult to get used to this kind of writing.
| Here's a typical example. I want to incorporate a figure to help me
| explain a concept. I need a TIFF or an EPS for print, and I need a
JPEG
| or a PNG for online. In fact, I need a high-res version for people on
a
| fast connection and a low-res version for people on dial-up. As the
| author, I should need only to say what figure I want. I should not
have
| to identify three files and tag them. The system should be able to
| figure out the rest.
Absolutely. And that is how we design the single source systems we
implement for our clients. In your example, the author would simply
place a TIFF in the source document. The system "knows" in advance that
TIFF images are to be converted to JPEG (or PNG) when the online output
is generated. It happens automatically and transparently. The author
does not need to include multiple images and does not need to apply any
special tags.
| Similarly, I should be able to incorporate all sorts of typographic
| niceties (em dashes, curly quotes, piece fraction, equations, exotic
| tables) in the source, and the system should be able to degrade that
| source gracefully for everything from Web pages to plain text email.
Absolutely, and this too is accounted for in the single source systems
we design for our clients. There is a predetermined mapping of each of
these typographic niceties so that, for example, an em dash is converted
to the appropriate HTML entity, equations are automatically rasterized,
and exotic tables are properly converted. Again, this is all
predetermined and handled automatically behind the scenes. There is no
need for the author to do anything special.
| Or I should be able to select XML tags to identify items and prices in
a
| table and later decide whether to pull the wholesale or retail prices
or
| to leave them out altogether.
And with an XML-based approach to single sourcing, this too would pose
no particular difficulty.
Consulting & Training on FrameMaker & WebWorks Publisher
Consulting & Training on RoboHelp
WebWorks Publisher Certified
Member, JavaHelp 2.0 Expert Group
Moderator, HATT & wwp-users
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Your monthly sponsorship message here reaches more than
5000 technical writers, providing 2,500,000+ monthly impressions.
Contact Eric (ejray -at- raycomm -dot- com) for details and availability.
Buy RoboHelp Deluxe starting at only $798: you'll get RoboDemo, the hot new
software demonstration tool that's taking the Help authoring world by storm,
together with RoboHelp Office. Learn more at http://www.ehelp.com/techwr-l
---
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 http://www.raycomm.com/techwhirl/ for more resources and info.
