Thoughts on "Two-Track Documentation"

["GALVIN, KATHLEEN" <KATHGA -at- SAFECO -dot- com>]

Andrew Plato's stirring statements and Tom Murrell's responses prompt me to
share some thoughts I have every time I read the list.

1.	Flippancy and wit in writing are tricky things. Often they are
perceived as only offensive. Unless you are Dave Berry, you should probably
play it straight, at least in writing. (I speak from sore experience.)
2.	Most of these things I see debated here are not up for grabs. By
this I mean that usability testing has shown, and continues to show, what is
effective writing and what isn't. That, to me, is the final authority. Does
this kind of writing do the best job possible? Can you prove it with actual
human beings? Case closed. 
3.	Usability testing has shown that having a clear perception of who
the audience is -- their skill level, their environment, their needs, and so
forth -- is the underpinning upon which good writing is built. The audience
determines the medium. After identifying the audience, it (not the writer)
determines the purpose of the document. Audience and purpose are the
foundation.
4.	Many of us in the field have been writing for years and getting by
on native talent and chutzpah, me included. No more. We have reached a place
where academia knows a great deal, if not more, than we do about how to
write effectively. Get thee to classes because you can seriously embarrass
yourself with flamboyant pronouncements that can be proved wrong.
5.	Let's cut each other some slack. Flaming and swashbuckling
pronouncements are the province of hormone-frazzled children. Let civility
reign on the list.
6.	Last and by no means least, don't flame me. I'm a saint. Ask
anybody.



Kathy Galvin