Re: A challenge to Andrew

["Tim Altom" <taltom -at- simplywritten -dot- com>]

What's missing is anything about interfacing with anything else or anyone
else. No mention of teams, business units, budgets, deadlines, or even
users. What is "readability" anyway? It's apparently whatever the "good
writer" declares it to be. In my view, the acid test of any technical
documentation is its measurable effectiveness. Anything else is opinion
disguised as judgement.

Andrew's list seems to indicate that the documentation effort focuses
squarely on the "good writer's" navel, when it fact it is the outcome of
many things, of which the writer is merely the most visible. If you doubt
this, look up Deming's principles of quality assurance and get familiar with
his organizational theory.

The idea behind consistently good documentation is not to rely on the
proclamations of self-styled "good writers", but on good design, good
implementation, good business practices, good training, and good testing.
Where Andrew and I part philosophical ways is that I have far less faith
than he does in the chest-thumping independent who proclaims himself to be
the key to all good documentation. Hogwash. Good documentation is the result
of good planning, consistent planning, TEAM planning. He adheres to the
"great man" theory, in which both history and sports are dominated by
standout individual players. I watched the Bulls in their glory years;
Michael Jordan had a fabulous supporting cast, meticulous practice, and an
excellent coach. Jordan prospered because he played in a good system, not
just because he had great skills. The record books are full of star athletes
who moved to different systems and ceased to be superior.

All of us labor in a system, whether we want to acknowledge it or not. The
better communicator, in my view, makes maximum use of the system and adds to
it. He does not sneer at using ANY system and, with hubris on display for
all to see, march off to do things his own way. In my view, not planning for
the client's future by engineering the documentation we do for him is an
abrogation of professional responsibility. And by engineering, I do not mean
"I write for him". I mean that we plan the document as part of the total
system, so that it can be reused and reassembled later with a minimal cost
to the client. What we do for him today is not just a one-shot, but should
be a basis for good documentation in the future.


Tim Altom
Simply Written, Inc.
Featuring FrameMaker and the Clustar(TM) System
"Better communication is a service to mankind."
317.562.9298
Check our Web site for the upcoming Clustar class info
http://www.simplywritten.com

----- Original Message -----
From: Paul Hanson <PHanson -at- Quintrex -dot- com>
To: TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>
Sent: Tuesday, November 28, 2000 9:03 AM
Subject: RE: A challenge to Andrew


> I don't understand, Tim. What's missing from Andrew's list?
>
> <snip>
> > "a good writer", which I take to mean "Andrew Plato", has mastery of
> > these four things:
> >
> > 1) Technical Accuracy
> > 2) Readability
> > 3) Writer's technical expertise
> > 4) Style (how can it make documents more interesting).
> <snip>
>



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Develop HTML-based Help with Macromedia Dreamweaver! (STC Discount.)
**NEW DATE/LOCATION!** January 16-17, 2001, New York, NY.
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.

Sponsored by SOLUTIONS, Conferences and Seminars for Communicators 
Publications Management Clinic, TECH*COMM 2001 Conference, and more 
http://www.SolutionsEvents.com or 800-448-4230

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