RE: Baiting for the single source rant (getting long)

["Swallow, William" <WSwallow -at- courion -dot- com>]

<snip>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. Therefore, they need different text, tone, and content.
Single sourcing degrades both since it must standardize the text across
multiple mediums. 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. </snip>

I think you're confusing single-sourcing with repurposing. Or maybe the
samples you are referring to were created by someone who made that error.
Single-sourcing is not the repurposing of information from one medium to
another. That's a part of it, but there's a lot more that needs to happen as
well.

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

It's a gray issue. In reality you're not talking Process A (simple and
works) vs. Process B (complex single-sourcing). You're talking Process A
(the "traditional" way) vs. Process B (a new method). Big difference. In
your scenario, tradition is gold and we should stick with it come Hell or
high water because that's the way we've done it for years, it's familiar to
us and we can do small tasks quickly. You see single-sourcing as a complex
way to do the mundane. I see single-sourcing as an efficient way to escape
the mundane (copy/paste whenever I want to duplicate something, for
example). It's all a matter of perspective. 

<snip>3. Most of the available tools are crude, unpolished, and require
extensive customization. Maybe when somebody comes out with
Single-Sourcing 2003 that does all the nonsense work for you, this won't
be such an issue. </snip>

Can you give me/us an idea of what tools you speak of and what this
"nonsense work" is that you speak of? It's hard to objectively weigh such a
vague comment.

<snip>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 tweaking, fiddling, and
bickering to build a system that MAYBE saves a few weeks worth of work. 
In the process, they become so distant from their actual jobs, that the
content becomes a secondary thought.  You end up with an exquisite process
that produces utter crapola.  </snip>

Hmmm... maybe we're talking apples and oranges here? SS is more of a
methodology than a "system". If writers are spending countless hours making
a technology bend to their whim, then they are not really single-sourcing,
but rather are trying desperately to repurpose information.

<snip>5. It destroys "contexutalism."  One of the largest problems (IMO)
today
is technical documentation that lacks context. The incessant mantra of
single-sourcing and information mapping has destroyed context and flow. 
Complex ideas require a "unity" of tone and description. When you chunk up
everything and package it into neat little shrink-wrapped bits, the
content as a whole suffers.  This leads to manuals where the information
lacks a consistent delivery. It also leads to "instructionalism" that is -
all instruction and no education. </snip>

Eeep! Big words! Run away!!! *g* First, let's not talk single-sourcing and
Information Mapping(tm) in the same context, as they are not the same thing.
Single-sourcing does not necessarily mean you blow info into smithereens and
then try to duct tape it back together. The point is to author information
that can be used in many different contexts and mediums. If anything, it's
the antithesis of info mapping.

</snip>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? </snip>

Again, you're thinking in context of repurposing.

<snip>7. The output always needs tweaking. Its never perfect, and getting it
perfect can become a nightmare. </snip>

Do you have data to back this up? I do know people who have successfully
single-sourced with no tweaking and no pre-production nightmares (well, at
least no more than any other writer experiences when preparing to publish
and ship).

<snip>8. Its value has been way overhyped in STC conferences. If you
listened to
the consultants, SS would be the solution FOR EVERYBODY. When in fact,
probably only 1 in 10 organizations would actually benefit from it. Most
organizations do not produce enough documentation to warrant such a major
investment in a complex documentation system. If you run the pure
financials on it, most SS solutions are terribly overpriced and fail to
yield real value. I wrote a post detailing this about a year ago. Just
scan for any response I made to that Tim Altom guy (who was a big SS
proponent.) </snip>

I agree that it's been over-hyped, kinda like XML, which is also widely
misunderstood. I don't think any decent consultant would push a methodology
as the holy grail of technical writing without first analyzing the extent of
the work and the types of deliverables required. I agree that it's not for
everybody, and it shouldn't be. As far as investment is concerned, the cost
is relative. Like you say, put a writer in charge who knows what he/she is
doing and you'll get good results. Anyone else would just be an idiot with
feathers in his/her butt. Now that doesn't mean it has to be a writer who
knows X tools, but rather someone who can size up a situation, determine
what needs to be done, and execute along those lines. The overprice is
directly related to bad decisions made by uninformed people based on
misinterpreted information or information from others who are uninformed.
Without being involved and knowing what work needs to be done, no one can
offer a dead-shot solution.

<snip>Is SS pure evil? No, its just overwrought. Its been touted as the
perfect
solution for everybody. I disagree.  </snip>

And I totally agree with you here. Again, it's being generalized and
immortalized by people whom the majority of which don't fully understand it
or at least understand it beyond how they've done it. The result: a lot of
misinformation and hybrid, mutt solutions that only fit one scenario.
Single-sourcing is not a commodity. It cannot be sold as a solution and
implemented as a fix. It's a methodology, one which has many different
implications depending on the scenario at hand.

<snip>Complex documentation systems do not make for happy customers. Rock
solid,
meaningful and insightful documents make for happy customers.  In some
organizations, handling massive tons of materials, SS can have real
benefit. But for the majority of mid-tier to small companies, there is
absolutely no value in SS. The money spend on SS should be diverted into
training tech writers to be more knowledgeable in the products and
technologies they are documenting. </snip>

I couldn't agree more, with one comment: the size of the company doesn't
matter. The information - its complexity, diversity, and application - is
what matters. Again, "money spent on SS..." is out of context. That's
basically saying "money spent on rationally planning your project..." It's
not a process, system, or any other tangible thing, at least no more than
clear-headedness, insight and innovation.

<snip>I have cleaned up more company's failed SS projects then I care to
mention. The situation is almost always the same. Some fire-in-the-belly
tech writer sold management on a SS solution. Then 4 to 6 months later,
there were no docs. The writers had spent all their time bickering over
tools, fonts, document specs, etc. and never had time to write the docs.
So the company has to quick, contract outsource provider (like my firm) to
come in and doc everything in a flash. In the end, costs have tripled,
docs are done, and the SS writers have absolutely nothing to show for
their efforts. 
Can SS work - sure. But, if you buy into SS be prepared. Its not a light
decision and it won't, necessarily, make life easier. </snip>

No, it's not a light decision, and not one to be made when you have
deliverables nipping at your backside. Perhaps this is why you've seen so
many failed attempts; people jump into it without thinking. No different
than "We need 100% HTML documentation. Let's write in Word/Frame/Ventura!"
or "Hey, we have a deadline 6 months from now, and need to get this
documentation out the door. Let's do it in Sanskrit!" It's doomed to fail
without a rational approach. If you only need HTML, then write in it! And if
you don't need to write in a 5000 year old dead language, don't!

***************** 
BILL SWALLOW 
Technical Writer 
C O U R I O N   C O R P O R A T I O N 
1881 Worcester Road 
Framingham, Mass.  01701 
T E L * 508-879-8400 x316 
F A X * 508-879-8500 
www.courion.com 
***************** 
THIS EMAIL CONTAINS CONFIDENTIAL INFORMATION
MEANT FOR THE INTENDED RECIPIENT ONLY. PLEASE
DELETE THIS IF YOU HAVE RECEIVED IT IN ERROR.

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

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.