Simple Economics

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

I wrote...

>> You should do both. If you don't have time - then I'm on the engineer's
side.
>> Raw data is ugly but more functional that pretty tutorials. Put the
tutorials
>> in on the next version."
 
Then Sierra Godfrey wrote:

> I'm not sure I can agree with this. If raw data is more important than steps 
> showing the reader how to perform the task, then my job is not necessary
here-> the engineer has already done it for me. 

This is really just a simple economics equation. A finished product cannot
exist without raw material. A car cannot exist without steel. Duh.

Therefore, the precursor to all decent documents is data: raw, ungainly
information. At the bare minimum, documentation must contain this raw, ugly
data in some form. Otherwise, the document is totally worthless. 

Beyond the raw data is where we come in. We force that data to make sense.
Either by organization, task lists, pretty pictures - whatever. Engineers
aren't very good at this stuff. So, they need you to do it. 

So, if you try and build a document without the raw data, you'll have an
exquisite pile of crap.  If you have only raw data, you'll have a pile of crap
that at least has information in it.  Therefore, you must have both: reference
and tasks. But if you can't then you at least need the raw material. Tasks with
out reference are cute - but don't deliver enough content.  

Content ALWAYS outweighs delivery.

Therefore, do both. Real simple.

Now, you can confound this with the idiotic advice of those want to protect the
"tender soul of the audience" and other pointless emotional crap. The fact is -
docs need accurate content and nobody cares about your concern for the audience
if the product doesn't sell. 


Andrew Plato 

Stop eating hamsters: http://members.home.com/aplato 


__________________________________________________
Do You Yahoo!?
Send instant messages & get email alerts with Yahoo! Messenger.
http://im.yahoo.com/