Re: Baiting for the single source rant - Bill's last words this t ime around

[Andrew Plato <intrepid_es -at- yahoo -dot- com>]

> The bottom line is that what this rant is about, is that we are all
trying
> to reduce the authoring of redundant text we have to author and maintain
> over a document's life cycle 

No we're not. I am not trying to reduce redundant text authoring. Many of
my clients could care less about this issue. We are way more concerned
with the technical accuracy of the text. God (aka B. Gates) invented
copy/paste to handle redundant text. We surely don't need to spend 2 years
and $900,000 to solve a problem I can solve with [CTRL][c] / [CTRL][V].

So here we go again - a massive non-issue that has been pounded  into tech
writer's heads.  What on earth is so awful about redundant text? What is
the weird cult of "THOU MUST REDUCE REWRITING."  As if this were just
ruining our lives because, *gasp*, I had to write the same thing twice. 

Okay, if you have to maintain 500 documents, you have a point. But most
tech writers I talk to are lucky to be holding down a library of 20 to 50
docs.  Moreover, at any one time, maybe only 5 to 10 of those docs are in
motion.  This is not something that warrants a massive structured
authoring system. You just need some basic version management and team
leadership. Its cheaper and it can be changed quicker. 

Last release we did for a client we had 6 docs and an on-line help system.
We rewrote the thing from the ground up in 3 months. When we needed
content from one doc in another - the writer opened the doc, copied it,
and pasted into the other. Ding - 15 minutes billed to the client. This is
one of the ways we saved a client $200,000 last year in tech doc expenses.
Keep it simple stupid - its going to change anyway. 

Also, some organizations change their documents so much for version to
version, that there is no real pressure to have some Fort Knox of well
organized information. You're making massive assumptions Bill that apply
in your environment, but not universally. 

Furthermore, a reduction in authoring redundant text is not synonymous
with quality documentation. If the original content is bad, having it well
replicated throughout 98 different documents won't much matter - the text
is still wrong. 

> 1. "Single sourcing" multiple outputs from a single master document.
> 
> This is applicable to documents which are structurally very similar, but
may
> have alternative elements relating to different product configurations
or
> (probably the most powerful use) or texts in alternative languages.
Texts
> that are common to all or several versions of the output documents are
> present only once, with variant text elements held side-by-side within
> structural containers (no elements in particular containers may be
> applicable to some outputs). The variant text elements are identified
for
> output processing by appropriate attributes to render the specific
> deliverable documents. 

You make one massive assumption here Bill - that ALL organizations
world-wide have highly structured information that rarely changes. This is
RARELY the case for most non-governmental organizations. In the software
industry especially. Version 1.0 to Version 3.0 of a product can be
dramatically different. Thus, you would be constantly rebuilding the
structure of docs anyway. 

A structured system would need to be so flexible and transparent, that
there almost isn't any reason to have one.  

> Tenix found this approach to be very successful for maintenance
procedures
> used by the ANZAC Frigates we are building for the Australian and New
> Zealand Navies 

Again, you're dealing with content that is relatively static in nature.
We've had this discussion before and came to this same conclusion then as
well. If you have static content that rarely changes, SS is a good idea.
If you don't - SS is not a good idea. So your circumstance Bill, is unique
and NOT indicative of most organizations. 

Hence the problem, your paper assumes that your experience at your
employer - a defense contractor - is universally applicable. If you tried
to implement your solutions at most software companies it would collapse
into a pile of goo. The content and the organization simple change to
rapidly to keep up with a complex, structured documentation system. You
would need teams of writers just to maintain the systems.

I know this because I've cleaned up numerous failed structured writing
efforts after management became enraged with unproductive writers
promising amazing efficiency that could never materialize - because the
writers were too busy building the system.  

The alternative, is to have a small team of skilled writers who know the
content well and can generate new documentation quickly. Structured
systems are used only as a secondary support mechanism and never as the
primary environment. 

> I hope this encourages more people to try.

I couldn't disagree more strenuously.  I hope this thread encourages
people to stop, curtail, or at least seriously reconsider their SS
efforts.  I've picked up the pieces on too many pie-in-the sky dreamers
who envisioned brilliant structured solutions. It all sounded great in a
meeting. It all sounds swell in an STC symposium. But when dollars and
time are on the line, a lot of those brilliant ideas turn to dust. 

What I would like to see is an honest tipping points evaluation - when is
SS a good idea, when is it a stupid idea.  If I were to take the general
rhetoric from your material and others as fact - I would conclude that SS
is ALWAYS a good idea. In fact, it isn't.  In my estimation - non
scientific of course - 1 in 10, perhaps 1 in 20 organizations would truly
and honestly benefit from SS. 9 of 10 to 19 of 20  would waste time and
resources better spent on training writers.

All complex technologies must endure this same struggle:  feature vs.
cost. At what point does some new widget become prohibitively too
expensive or too difficult to produce such that the organization cannot
recoup real gains. When you work for a government agency (or a government
contractor) where profit is not a consideration (or a minimal one) and you
have the luxury to plan things out over eons - SS can make sense. But out
here in the private sector its not so easy. Speed, profit, and ROI are
constant pressures.  

Andrew Plato 

__________________________________________________
Do You Yahoo!?
Get email alerts & NEW webcam video instant messaging with Yahoo! Messenger
http://im.yahoo.com

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

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.