Re: John Galt: Lover of Standards

[Andrew Plato <intrepid_es -at- yahoo -dot- com>]

Eric Ray said:

> er...but the starting point for the cycle (the hypothesis) itself
> requires certain assumptions or ground rules. Where do we get the 
> ground rules that allow us to develop a hypothesis? From
>  * standards
>  * academic research 
>  * experience
>  * other people's opinions
>  * guesses
> 
> The scientific method _requires_ that you start with assumptions (or givens,
> or whatever you want to call them). They're just not always explicitly called

> out. For example, when scientists are preparing for a space shuttle launch,
> they start with "assuming Pythagoras was right and the square of the
> hypotenuse really is equal to the sum of the squares of the other sides,
> and assuming that Copernicus was right about how the solar system works,
> and assuming that Einstein was right about e=mc^2", then we can do this. 
> 

> I disagree. SECOND, they set up their working assumptions (computer literate
> users, expecting API documentation, don't care about spaces after a period or
> punctuation within quotes, using this process or style guide or whatever).
> THIRD, they write the document in accordance with the assumptions they've
made
> (or, to return to fighting words, they write the document in accordance 
> with the standards they use).  If you do it this way, you don't waste time 
> on trivial decisions, don't have to rework the document again, and don't 
> document stuff that doesn't need to be documented or miss stuff that does 
> need to be documented. If I write "documentation" about product A without
> clearly specifying my standards/audience/methodology/style etc, I'm
> potentially wasting my time and my readers time. If I clearly understand 
> the assumptions and audience and standards (API docs, not user docs, 
> for example), I can more efficiently write good documentation. 

So I say 

1. Learn
2. Write
3. Tweak

You say 

1. Learn
2. Make assumptions and audience analysis
3. Write
4. Tweak


I think you're splitting hairs here Eric.  I also think that placing the
"audience analysis" section into its own category sets up a problematic
situation.  Also there is a very large difference between assuming ?square of
the hypotenuse really is equal to the sum of the squares of the other sides?
and assuming your audience will like screen shots that are 1 inch tall. One has
a few more centuries of testing.   

It seems to me the best way to comprehend the assumptions, audience, etc. is
while learning what you are documenting.  I see the "Learn" phase as a holistic
combination of learning about the product and making your assumptions.  Part of
learning is assuming. 

The reason I say this is because plenty of writers spend a ridiculous amount of
time writing up detailed, exquisite "audience analysis" documents.  Then half
way through writing the document, someone tells them something that alters that
analysis.  I have watched writers defend their "audience analysis" with
complete disregard to the information presented to them. If you establish too
many standards up front, it is difficult to throw them away later if necessary.
 

Therefore, I feel it is unecessary and undesirable to make any assumptions or
"audience analysis" phase overly formal. These types of work are just another
way to avoid the inevitable which is that you have to plop your butt in a
chair, figure out what the product does, and explain it to other people. 

I guess that is ultimately why I rail standards so much.  They are consistently
used by tech writers as a tool to avoid doing their jobs - which is to write
documents.  It is much more entertaining to sit around and think about the
audience and make snide comments on TECHWR-L about the gloriousness that is
bold colons than to sit your big ass down and write something.  

Standards are fine and wonderful, but they are tools.  Much in the same way
that sitting around complaining about FrameMaker vs. Word is an utterly useless
endeavor - sitting around masticating about standards all day is useless.

A technically accurate but inconsistent document is ALWAYS preferable to a
document with inaccuracies or omissions.  ONLY tech writers care about
standards and consistency.  Users might notice it, but they will ALWAYS notice
if you left something out or said the wrong thing.  


Andrew Plato



=====

__________________________________________________
Do You Yahoo!?
Bid and sell for free at http://auctions.yahoo.com