Sorry state of the art listowner jerks Brian

["Walker, Arlen P" <Arlen -dot- P -dot- Walker -at- JCI -dot- COM>]

Does that about cover the range as we segue this to a more apropriate
subject line?

Brian makes a good point of criticism, but, as is usually the case in
quality improvement projects, failed to complete the circle.

The state of the art of documentation is generally percieved as bad, not
only by the general user but by experienced practitioners in the field.
One or two opinions can be shrugged off as matters of taste, or as
misguided. If a hundred people I meet on the street comment on my odor, I
probably should revisit my decision that the moisture on my shirt is rain.

But that leads us to the point where Brian and Damien, who followed after
him, left us: standing in the street surreptitiously smelling our pits.
The problem comes at the next step.

Brian wanted us to be discussing what we can do about it. OK, I'll bite:
what can *I* do to improve Panasonic's manuals (not casting stones at
Panasonic, just selecting them at random). We've had discussions of
Information Mapping and other methods for organizing content. We've had
discussions on the appropriateness of PDF, HTML, and other mechanisms for
delivering docs. We can discuss these topics again and again (in the case
of some topics, such as a recent thread which came through yet again just
recently, it seems we discuss blessed little else except them, and there's
a high probability it will raise its ugly head again in this discussion,
being the panacea that it is perceived to be) but that doesn't do anything
to change the quality (or lack of it) in documentation.

So guess that's the question I would have liked Brian to answer before he
wandered off into the darkness. It's a problem. I agree it's a problem.
Now, let's a have a suggestion as to what we, as a list, can do about it.
We could critique specific manuals, but many of the list members are
independents, and why should we expect them to give away for free what
they earn their rent money doing? We could discuss how material should be
laid out, but this is the Internet, remember, and TMTOWTDI is the order of
the day. (The motto of the Perl community, if you're puzzled by the
acronym. It stands for "There's More Than One Way To Do It.") The problem
with deep discussions on those subjects, however, is that our employers
don't pay us for them; they have this entirely unreasonable idea that we
should be working on their projects, not furthering the techwriter agenda.
As long as we get specific help we can point to, we can justify our
helping others. But if the list content suddenly switches to a theoretical
discussion on principles of TW, then our employers will, for the most
part, lose interest in suporting it. (After all, their docs are perfectly
fine. They are produced to the company specifications, aren't they? The
problem is with all those *other* companies.)

Maybe what we're doing is making an unspoken assumption about this list
that is unwarranted. Maybe we're not covering the basics of what
information should go into a manual because we're making the assumption
that everyone here already knows the answer to that. Maybe we're making
the assumption that the professionals on this list aren't the ones
producing the bad manuals. (Then again, I can remember at least one person
on this list deeply criticizing a manual I found to be eminently
satisfactory, and have experienced similar discussions on other lists, not
related to writing.) Maybe my digestion isn't functioning well this
morning and that's what is making me such a pessimist.

Like Damien, I find about 90% of the list traffic is crap. But my years in
science fiction have adequately prepared me for that: Sturgeon's Law (Ted
Sturgeon postulated it, in "Sturgeon Is Alive And Well" among other
places) states that 90% of *everything* is crap. Given that perspective, I
don't have grounds to complain, especially as I realize the 90% I would
draw a circle around isn't the same 90% that Damien, Brian, or Eric would.
Brian wants a deep discussion, Kristin (sorry, nothing personal, your name
just happened to be visble in the incoming mail list) has a colleague that
just wants to meet a deadline. If the list devotes itself to Brian's
cause, how many Kristins will go away?

For anyone out there within the sound of my keyboard with similar
sentiments to Brian's, my advice would be simple. You don't like the
subject matter? Then post something. You might be surprised at what
happens.

Have fun,
Arlen
Chief Managing Director In Charge, Department of Redundancy Department
DNRC 224

Arlen -dot- P -dot- Walker -at- JCI -dot- Com
----------------------------------------------
In God we trust; all others must provide data.
----------------------------------------------
Opinions expressed are mine and mine alone.
If JCI had an opinion on this, they'd hire someone else to deliver it.

 From ??? -at- ??? Sun Jan 00 00:00:00 0000=