Re: Single Sores

[edunn -at- transport -dot- bombardier -dot- com]

I'm not sure I want wade into this one, but here I go again. This is very long,
so please forgive me.

In asking the questions about whether to consider a single source type process
or not, there seems to be a missing perspective and have some of them are
backwards.

<<1. Do we have a lot of time (months perhaps) to design, test, and enhance a
complex SS system?>>

No process should be designed as an all or nothing venture. Processes should
leverage and simplify (where possible) existing practices. Any good complex
integration should be accomplished with a gradual transition. Any system that is
implemented and cannot produce results is flawed and deserves to crash and burn
and enhancements should be possible without holding up production. No process
should be designed that is not flexible enough to evolve just as no process
should be hyped as the be all and end all of instantaneous solutions.

<<2. Is the content of the documents:
   a. Stable, that is not prone to wild changes in tone, direction, or basic
content?>>

In fact the more unstable the content, the more helpful single source process
will be. If content is stable it doesn't matter how complex the system, you just
get to work and start writing with the secure knowledge that you are approaching
the end of the work.

 <<  c. Straightforward, that is not requiring extensive audience education?>>

The less straight forward the more you can leverage single source and data
management systems as a cost effective solution to the creation and maintenance
of documentation. Unless you wish to make the claim that aircraft, warships, or
public transit systems are somehow "relatively straightforward technologies ".
Seems to me to be a rather strange twist in logic that a straight forward
technology would require a large doc set (see further on). I'm afraid I'm not
sure even the most complex of computer systems can match a warship in terms of
required documentation and they would still have a lot to measure up to in the
transport industry where we are producing multiple cross-referenced manuals
totaling tens of thousands of pages as well as interactive maintenance and parts
systems.

<<3. Are we willing to scrap the system at a moment's notice to fulfill a
deliverable?>>

Here Andrew has it right. If the system can't deliver it should never have been
used. As with question four, any system should deliver, aid production, and have
a "tangible benefit down the road that will save money and time without
negatively affecting the quality of the material".

<<5. Are we able to adequately generate documentation using "traditional
methods?">>

I think Andrew has never acknowledged how many of the pro-process and single
source people are right behind him on this one. If you aren't already organized,
don't expect some system to come in and miraculously solve all your problems.
It's like trying to design a database and then shove existing poorly organized
and out of control information into it. What you have to do in reality is first
organize your existing information and then build the database to hold it. If
your filing system is throwing crumpled paper into a box, it's not a shiny new
filing cabinet that will solve your problems.

<<6. Do we have buy-in from all related parties, including engineering and
management folks?>>

You need management buy-in, but it's surprising what you can do behind
everyone's back. Leverage existing engineering, design, and production processes
and study how they affect your own. Help engineering by providing them with a
database to track their documentation (lowering their workload), provide another
front end to management to track delivery of these docs (lowering their
workload), and add the couple of flags you need to show you project status and
required updates and inclusions for documentation (thus eliminating a huge load
of drudgery for yourself). While helping everyone, you've tricked them into
doing much of your current work.

<<7. Can the team professionally select designs and templates without
in-fighting?>>

A writer's job is to write not to design templates. No team should be assigned
to template design. The poor excuse of writers arguing over templates is more
likely without a document/information/single source management system than it is
with one.

<<I would estimate that 1 in 10 perhaps 1 in 20 organizations could answer all
these questions yes. I would also estimate that most of these organizations
would be dealing with the maintenance and management of large doc sets,
regarding relatively straightforward technologies that are not prone to massive
changes in design and concept.>>

<<SS docs often read in a herky-jerky manner because the chunks of information
were written by different authors, at different times, with different levels of
skill with the content. You also see a lot of material that was obviously
written by an engineer and lightly wordsmithed by the writer.>>

And I've seen horrendous handbuilt help systems and useless computer
documentation that had no connection with a single source system that shows
these traits as well. Does that give me the right to pronounce upon and judge
the computer documentation industry as a whole? If the techwriting industry was
to be judged by some of the garbage out there I'd wonder if any of us could find
anyone to employ writers at all.

As for some the rest I can't help but stand back in awe and amazement:

<<I've gently nudged projects this direction with great success. We don't SS the
entire doc set on day one, we slowly nudge bits and pieces that lend themselves
to a high degree of organization and reusability. We've don't this using *gasp*
Microsoft Word and Access databases.>>

<<The bottom line - you want to SS:

1. Get to know the content first.
2. Write the docs, the "hard way."
3. Publish them and make readers happy.
4. Then nudge your processes into more organized system.>>

Proof and confession, from Andrew Plato himself, that he develops processes and
actually repurposes /reuses information through SS tools, and not cut and paste,
when appropriate.

Andrew, were YOU avoiding YOUR real  work when you designed that Access
database? Because if this WAS part of your REAL JOB, then perhaps you might
understand, or admit, that many similar tasks (including single source, template
design, process development, and others) are indeed part of many Techwhirlers
real jobs and why some take offense to being belittled as a group by posts with
mocking titles and filled with hyperbole such as:

<<And I yell "Things technical writers use to avoid their real jobs!">>

Eric L. Dunn



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

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.