When it is right to be wrong?

Subject: When it is right to be wrong?
From: John Cornellier <tw -at- cornellier -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 06 Feb 2002 17:00:37 +0100

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.


Follow-Ups:

Previous by Author: How to kill morale
Next by Author: Re: Search utility for HTML documentation
Previous by Thread: ADMIN: Re: Home network security WAS Re: upgrade from 98 to XP
Next by Thread: RE: When it is right to be wrong?


What this post helpful? Share it with friends and colleagues:


Sponsored Ads