RE: Baiting for the single source rant [long]

["Michele Marques" <marquesm -at- autros -dot- com>]

Andrew Plato wrote:

> 1. It tries to be all things to all formats.  On-line help and print media
> are fundamentally different mediums. Readers use them in fundamentally
> different ways. [... good points with regards to this type of
single-sourcing...]

(1.1) Single-Sourcing is not necessarily between formats. For example, we
have a number of different hardware devices that are variants of each other
(e.g., a medical depot that is mobile or is stationary). It is effective to
single-source the user's guide for these variants with FrameMaker and
conditional text.

(1.2) Sometimes due to a lack of manpower resources, there is a choice
between not having any online help at all or single-sourcing the manual and
on-line help. If all your users always have access to the paper manuals,
then there may not be a point to single-sourcing this information, which may
be just a replication. But in some environments (e.g., enterprise-wide
software where only a few people see the paper manuals), having essentially
a paper manual on-line may be useful to the users. This can also be helpful
in environments where the software changes frequently and updates to the
on-line manual can be downloaded with the updates to the software.

> 2. It unfocuses the writer into managing a large complex process and crude
> tools and not the content. These systems require extensive setup and
> management, and so far, most of the single-sourcing project I have seen
> required writers to jump through far more hoops than a manual methods. Its
> like the recent post where somebody too 4 hours to code a macro in Word
> when copy/paste would have acheived the same results and taken 4 minutes.

If you are only producing your manual/help/etc. once, then single-sourcing
may not be worth the initial set-up effort. If you have frequent updates,
resulting in new documents being generated, then the initial set-up can
quickly pay for itself. In my example of (1.1) it took me less than an hour
to re-do the template for single-sourcing. It took about a week consulting
with the hardware team to synchronize the hardware manuals, which had been
previously maintained as separate files. Now whenever a technical writer is
sent a change, the writer immediately notices if the old version was flagged
for multiple devices and spends 5 to 15 minutes finding out whether the
change applies to all of those devices.

You might think that it is equally easy to copy and paste the information
into multiple manuals, but
* it takes more time to open multiple files and locate the same information
in each file to verify which manuals might need updates
* when the writer is in a crunch, that copy/paste may be postponed - and
then forgotten
* manuals will become out of synch, resulting in incorrect manuals, and also
resulting in extra time to clean-up

> 4. SS is often used to avoid the "real" technical writing work. Rather
> than just sit their rumps down and produce the documentation, writers
> obsess and fuss over SS systems. They spend months [...]

I could spend lots of time copying and pasting text into different files and
verifying and re-verifying that differences in manuals are by design instead
of inaccuracy. OR I can spend a little time setting up some single-sourcing
and afterwards spend a few extra minutes to update all the variations of a
manual at once (saving time to write other manuals or learn more about our
new technologies).

> 6. It is not always a time saver.  You spend 4 months to set up a system
> to get back what? A few weeks worth of reusability?

Of course, you always have to decide whether single-sourcing makes sense for
your situation and how much time to invest. Spending 4 months to set up a
database to generate the manuals I mentioned would not have been worth the
time (or expense) for the savings I achieved. For this case FrameMaker and
conditional text worked well. And if there devices were not going to change
(or would have such radical changes that the manual would be completely
re-done), even the small amount of time to set up this single-sourcing might
not be worthwhile.

I have other manuals where spending 4 months on a database would actually
make sense, but in thinking of the short term, it is probably cheaper to
hire an additional writer and use a simple database or spreadsheet to keep
track of where information is re-used.

    - Michele
------------------------------------------------------------------------
Michele Marques, Technical Writer
AUTROS Healthcare Solutions, Inc.
marquesm -at- autros -dot- com <mailto:marquesm -at- autros -dot- com>

This material is intended for the use of the individual
to whom it is addressed and may contain information that
is privileged, proprietary, confidential and exempt from
disclosure. If you are not the intended recipient or the
person responsible for delivering the material to the
intended recipient, you are notified that dissemination,
distribution or copying of this communication is strictly
prohibited.
If you have received this communication in error,
please contact the sender immediately via e-mail and destroy this message
accordingly.





^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A landmark hotel, one of America's most beautiful cities, and 
three and a half days of immersion in the state of the art:
IPCC 01, Oct. 24-27 in Santa Fe.  http://ieeepcs.org/2001/

  +++  Miramo -- Database/XML publishing automation.  See us at  +++
  +++  Seybold SFO, Sept. 25-27, in the Adobe Partners Pavilion  +++
  +++ More info: http://www.axialinfo.com  http://www.miramo.com +++

---
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.