When it is right to be wrong?

[John Cornellier <tw -at- cornellier -dot- com>]

A little while ago [Darren Barefoot, I think] wrote:

"Get it done, then get it right, then get it pretty. ... I'd rather have a complete documentation set that's 90% accurate than an incomplete doc set that's 100% accurate."

I agree about the pretty part. But I can't think of any situation where inaccurate documentation is better than no documentation.

I read "90% accurate" as meaning "10% inaccurate".

Inaccurate doc is worse than no doc 'cause you waste your time with it. Plus it causes bad will and makes users distrust documentation (don't we all know it).

Over the past few weeks I've learned PHP, MySQL, and a bit of Apache, and built a website with them, installed some new audiovisual gear, set up an ISDN virtual PABX, and had both my cars in for servicing. So I've 
been at the user end of the documentation stick.

In two cases I encountered inaccurate doc. In the first case a wiring diagram caused me to waste time trying to troubleshoot something that could never work; in the second case I spent a long time installing software I did 
not need. On the other hand, in the PHP documentation I hit a spot where they just say something like "this function exists, but we don't have documentation for the parameters yet". OK. Fine. Would it have been better 
for the doc writers to have taken a guess at the possible parameters?

Dunno, maybe I lack vision. Could someone write an article for the STC mag "Adding Value With Your Inaccurate Documentation"?

John Cornellier



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Collect Royalties, Not Rejection Letters! Tell us your rejection story when you 
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of 
your book. What are you waiting for? http://www.iuniverse.com/media/techwr

Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ and check it out.

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