When it is right to be wrong?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

John Cornellier quoted someone as saying "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.", then
wondered: <<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".>>

Perhaps it's a question of the nature of the inaccuracy? I don't think
there's much problem telling a reader to click the "OK" button if the button
actually got changed to "Okay" or "Continue" before the product shipped but
after the docs underwent final review; most readers will still be able to
figure out this inaccuracy. The problem comes when the inaccuracy is more
serious: if you say "click" instead of "don't click", for instance. So if
you're under the gun and can't do the job you'd like to do, the accuracy you
must aim for involves writing a sufficiently close description of reality
that the reader can succeed at the task, even if it takes a bit of thought
to do so.

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

The first one is obviously more serious, since an incorrect wiring diagram
could damage you or the equipment; in a case like that, if you can't
describe the process adequately, you're better off including instructions
such as "consult a qualified electrician". The second problem is less
serious, though awfully annoying. A good audience analysis would have
revealed that the first thing readers want to know before doing the
installation is when and why they should be doing it--and when they
shouldn't.

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

Not okay, and not fine--particularly if the function could cause harm or
loss of data; in that case, better by far to not reveal its existence than
to encourage readers to risk problems by experimenting with the function. If
the writer had the time to debate whether it was okay to write that
sentence, and the developers had anything like a target spec for the
function, then both had time to provide at least skeletal documentation, as
well as a note saying "check our Web site at www.example.com/docupdates to
see whether we've had time to document this function." The latter is
obviously better, provided you have a documentation update site, because it
helps users find a solution that may not have been available when the
product shipped.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html

"Any sufficiently advanced technology is indistinguishable from a
personality, and an obnoxious one at that."-Kim Roper 

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