Re: Single Sores

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

<<If content is in a constant state of flux, how would putting into a single
source system make life easier.>>

Because you just put the information into the system as it becomes available. If
it changes, change the information in one place and it changes everywhere it is
used. No need to re-engineer or hand check the created pages for old references
or out of date information. Even if the information isn't to be used in several
places, the information management system ensures you have the various pieces of
data for each of the thousands of parts to be documented. If I only have five of
the 12 or so data points/procedures required, I enter those that I have and move
on knowing that I (or someone else) can identify the missing parts later and
fill them in.

<<Its a question of stability, Eric. Many of these aircraft and warship projects
may have massive tons of documents - but the documents don't change very much.
Contrast this with software documentation that is arguably smaller in quantity,
but changes much more rapidly. In the three years my company has written docs
for one client, we've  re-engineered the docs 3 times because the products
changed.>>

Sorry, but you don't have a clue as to what you are talking about. I have worked
with software development for users documentation in the transit industry, but
wouldn't dare to try and compare it with the complexities of documentation in
the network security area. Can you back up the statement that these documents
don't change very much or very rapidly? If there are multi-million dollar mile
stones to be reached and the equipment is out of service due to a technical
problem, it's amazing how much retrofit work you can get done overnight.
Contractually, the retro-fitting isn't accepted until it's documented.

It's nice to be told by someone time and time again that all the hard work and
frustration that has gone into a few years of work (for one project) is stable,
simple, and straight forward. Hyperbole can quickly cross over the edge and
become insult. Perhaps if you'd listen to the likes of Bill Hall and others
who've shown the merits of single source environments (and jobs that involve
something other than the computer industry) you'd understand. Bill Hall's
examples have been thouroughly detailed and show how complex a task it is to
produce navy documentation and the problems faced and solved by single sourcing.
And his posts covered both the creation of new documentation and the maintenance
of existing documents. After the berating he and others were administered, is it
any wonder there isn't much discussion like the myriad of approaches with FM and
WWP/MIF2GO and other products to create computer documentation and online help
from one source? Go on over to the framers list and there are dozens of great
working cases.

The only thing that is stable about the documentation of aircraft, warships, or
trains is the required output format and organisation (but not in the rail
equipment world). The content can change constantly. A coworker who worked for
U.S. Airforce documentation projects was employed exclusively to implement
changes to content. I have no doubt that the only time the documentation content
for trains, planes, or warships becomes static is the day they crash, sink, or
are scrapped. And only then because the documetns suddenly become descriptions
of what they were and not what they are. They all only experience varying
degrees of stability after commissioning and before refitting.

For the last documentation set we worked on, the organisation has had to be
reworked dozens of times. And, as we have to document what is for all intents
and purposes a prototype until the first few hundred are produced, content is
also a continuously moving target. Add to the mix that many documents that need
to be integrated come from suppliers and in many cases you have to take
configuration management into account as well. Only re-engineering once a year
seems like childsplay in comparison with the circus tricks we've had to perform.

And not much of this work is "simple" technology. Unless of course you consider
complex hydraulic, electric, pneumatic, mechanical, and electrical system and
computer network integration "simple". I'm sure all the laid back workers at our
aircraft division would also love to hear how stable, slow changing, and
relatively simple their work environment is.

<<I make light of this because I find the incessant need for people to "avoid
their job" to be one of the most frustrating things about work. They basically
don't want to work - they want to TALK about work. They want to leap ahead to
the "interesting stuff" and brush past the "hard stuff.">>

Perhaps if the person asking the question was first identified as someone trying
to avoid work then this argument would hold true. Often however, it's someone
with a genuine question looking for guidance.

<<I understand that some people feel threatened and mocked by me - I am a vocal
opponent of something that they very firmly believe in. I feel the same way when
some derisive Penguinhead trys to tell me that these WinNT-based security
appliances we sell are crap. It hurts because I've invested a lot of time (and
money) into developing these appliances and I think they're awesome. But, the
fact is - they have weaknesses just like anything (including Linux) else. And I
don't always want to hear those weaknesses.>>

I'm not sure threatened and mocked are the words I'd choose. Insulted and fed up
may be better choices. We should be talking about the weaknesses and STRENGTHS
of various approaches and the words crap and "Penguinheads" or "avoiding your
real job" should never enter the discussion. Much like the wholesale dismissal
of work environments, tools, and approaches, as well as professional expertise
based on personal exposure to a few lazy employees or style/font jockeys trying
to claim to be technical writers.

Fight against those that use hyperbole and you'll find that hardly anybody would
disagree. Keep painting everyone in a certain area with the same brush and
you'll continue to alienate yourself from many on the list. Unfortunately, a lot
of very professional help and guidance has been silenced on the list. Past
discussions brought out many experts with real life experience with all sizes of
documentation mangement projects. This time Bill Hall ventured out only once.

Instead of being derisive onlist, EVERYONE should highlight the things to do and
the scenario in which the approach is best used. Instead of bitching and
insulting, why not outline how to build a limited single source project with
MSAccess and MSword for example? Be honest about when it is too much to be of
use and when it would be too little. I'm sure more on the list would be
appreciative of this approach.

Hyperbole about what's bad about something is just as repugnant as hyperbole
about it's virtues. IMO

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.