Re: Baiting for the single source rant

[Bruce Byfield <bbyfield -at- axionet -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.

This is the conventional wisdom. But I suspect that the two have more in common
than is usually assumed. Most importantly, users scan and only read as little as
possible in any detail.

>  I can always tell when a manual has been single-sourced,
> because it reads like an on-line help system and lacks context for each of
> the technical concepts.

I agree that lack of context is a problem, but it's as much a problem for some
types of on-line help, too, especially when hardcopy isn't provided. And how do
you know that it's due to single sourcing, as opposed to writers who don't know
their subject very well?

> 3. Most of the available tools are crude, unpolished, and require
> extensive customization.

This point suggests a difference of approach. For some people, at least, the
idea of single-sourcing has less to due with specific tools as with design and
style. So long as you keep these concerns in their place (and I strongly agree
that, as a buzzword, single-sourcing has been ballooned out of all relation to
its importance), they can be useful. But, if they become ends in themselves, or
substitutes for subject knowledge, then the writers aren't doing their jobs.

In a tool-based approach, the value of the tweaking probably varies with the
project. If the project is one-off, then tool-tweaking probably isn't
worthwhile. However, if the document is going to be revised many times, then the
effort spent tweaking during the first round might be made up on subsequent
revisions - always assuming, that is, that the tweaking is documented or passed
on to the writers who do the subsequent revisions.

> The output always needs tweaking. Its never perfect, and getting itperfect can
become a nightmare.

Again, the usefulness of singlesourcing depends on keeping it in perspective. To
take another example, you can't expect to design a template in which all the
page breaks fall where you'd like them. But, usually, in a manual, it's not a
good use of your time to tweak every single page individually, or to obsess over
the template to produce fewer bad breaks; a point comes when the design is good
enough and you have to move on. Similarly, I seriously doubt that any method
will produce perfect singlesourcing. However, if you settle for "good enough,"
you might save time.

--
Bruce Byfield bbyfield -at- axionet -dot- com 604.421.7177



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

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.