To single source or not?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

A confused user of single sourcing (surely one of the longer names in our
esteemed gathering <g>) opined: <<Single sourcing seems a great idea to
technical writers that are under  tremendous pressure. You write one source
document and then use it - maybe with some modifications in conditional text
- to create html help, html etc.>>

So far so good, provided the phrase "maybe with some modifications" doesn't
get lost in the shuffle. You simply can't (and can't simply) make one piece
of text work equally well in print and online, and for a variety of reasons;
for example, printed and online material typically serve different
functions, and although it's possible to combine the two, that takes
considerable planning to do well. Perhaps more significant is that what
you're saying and how you say it both change to reflect changes in the
medium.

<<I opted to use single sourcing as that seemed the only way that I could
keep up with the company's incredible deadlines. After the program was
bought and I had created my first set of documents, I started getting a lot
of flack from the Head of R&D. He wanted each set of documents to be written
with a different style.>>

That fits with my prejudices, so I have a hard time refuting the manager's
assertion. The question is whether the differing style choice is purely
personal preference on the part of the manager, or an attempt to tailor your
documentation so that it better fits the needs of the intended audience. If
it's personal choice, it's worth debating; if the results produce better
documentation, you need to figure out how to make the process reasonably
painless. For future notice, if this guy is the one who can approve or
disapprove your work, make sure you get him involved in approving your
proposals so that you both agree on where you're headed with the information
and don't get any unpleasant surprises when it comes time for reviews.
(Provide samples first to get approval; if you proceed without this
approval, you may need to revise everything from scratch, and wouldn't it be
easier to avoid that and just write everything once?)

<<He wanted no screencaptures in the html help.>>

That can be a good thing, or a bad thing. If it removes visual context
that's necessary for comprehension, you should fight him on this decision.
But don't fight by butting heads: fight by demonstrating why your approach
is easier and faster to produce (e.g., why describe "the third orange
button--not the blue ones--from the bottom in the third row from the left in
the middle quarter of the dialogue box" when you can just show it?) and
makes the information more usable. If the graphics really don't fill this
role, then he has some justification to his request. The truth probably lies
somewhere between these two extremes: sometimes you need the graphics, and
sometimes they're just <ahem> window dressing.

<<Was I wrong to suggest single sourcing? Is it generally not an acceptable
solution?>>

Single-sourcing is a great idea in theory, and even in practice once you've
learned to do it well. But it's a far more complicated approach than writing
separate versions, since you need to rigorously examine what you're trying
to achieve through single-sourcing. The main flaw in most single-sourcing
efforts that I've encountered is that the designers of the information
didn't rigorously determine what information belonged online and what
belonged in print. If you don't do that exercise, you won't reach a
satisfactory solution. My personal experience has been that the two forms of
documentation don't overlap nearly as much as most people think. Similarly,
I've come to the following conclusions about the breakdown between online
and in-print:
- Reference information belongs entirely online, tied to the appropriate
parts of the software by contextual help, but also available from _anywhere_
in the software via a good index and table of contents.
- "Teaching" or "what you need to know to use this product" information
belongs exclusively on print, or in a well-designed online tutorial (e.g.,
based on interactive "learn by doing" wizards).
- "How to" information (tasks) belongs to both forms of documentation to
some extent, and this is where single-sourcing makes the most sense. Task
information should be available so it directly supports the user's task
(i.e., onscreen, so users don't have to flip back and forth between the
screen and the manual), but where the information supports broader concepts
(how to link a series of tasks to produce a final objective), it probably
belongs in print.
***Please note***: This is a very simplistic breakdown, and has obvious
exceptions. But as a starting point for your planning, it's a good one. Just
don't forget that it's simplistic, and that you'll have to apply my
recommendation with your brain engaged.

<<2. What does one do about different types of documents needing different

styles of writing?>>

"Different styles" is usually a clear sign that you have different
audiences, or at least different audience goals. That suggests different
presentations of the information, and thus, little overlap. Consider the
difference between the goals of reference material ("how does the software
work") and instructional material ("how do I get the software to do what I
want") and you'll see the point: different goals, thus different writing
styles.

<<Do professionally designed help files contain screencaptures?>>

Where necessary (see above). Unfortunately, "necessary" can be a judgment
call sometimes.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca

"Technical writing... requires understanding the audience, understanding
what activities the user wants to accomplish, and translating the often
idiosyncratic and unplanned design into something that appears to make
sense."--Donald Norman, The Invisible Computer