Dispensing with documentation reviews?

[Geoff Hart <ghart -at- videotron -dot- ca>]

Ann Pai reports: <<I'd like your take on this from both ethical and 
practical perspectives. I've been given a friendly heads-up from 
management that we may need to send out a large documentation set for a 
relatively new, as-yet-undocumented product without review.>>

This is a bad idea from many perspectives. Even minimal technical 
reviews ("just fix the disastrous errors") turn up problems that must 
be fixed. There may be very significant legal liability issues from 
sending out untested documentation. If you test something, it works 
fine, and someone gets hurt or suffers other types of damages, at least 
you've shown due diligence and have some defence against a lawsuit; if 
you didn't even try, I suspect a judge would rip you several new 
orifices. Enlisting your legal department in this "discussion" may give 
you considerable support.

<<if the documentation isn't finished for the customers who want early 
product releases, I may be asked to "wrap up whatever I have" and send 
out the documentation as is... Because our other writer is facing a 
similar situation, it appears to be a trend:  it's okay to send out 
unreviewed or even incomplete documents as long as we label them "early 
release.">>

Also a bad idea, and for the same reasons. Moreover, anything not 
documented or documented poorly will annoy your customers. If  your 
competitors are better organized and annoy the customers less, guess 
where your current customers will take their business?

If this is really a trend, do two things as soon as feasible. First, 
learn triage: identify what your customers absolutely need to know and 
what will hurt them if they don't know it. That's the only important 
thing to document if you have no time to do anything else. Other stuff 
is certainly important, but falls into the category of "it would be 
nice to do a job we could be proud of". A comprehensive _overview_ of 
the main things your readers need to know is much better than a perfect 
description of only a small part of the overall product.

Second, start figuring out how you can get documentation ready sooner. 
This requires some buy in from the developers and their managers. This 
can be boiled down to one oversimplified statement: If nobody takes 
documentation seriously, you won't be able to produce good 
documentation. Get documentation included in the development plans, 
freeze interfaces early enough that you can document something 
relatively stable, and so on. Very difficult to do.

<<Our "early release" customers usually expect some software features 
to be incomplete...>>

If you can get them to complain about incomplete or inadequate 
documentation, your managers will sit up and take notice. You can then 
explain how to eliminate these complaints. If the customers are happy 
with what you're giving them, why would management ever consider 
changing things?

--Geoff Hart   ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

SEE THE ALL NEW ROBOHELP X5 IN ACTION: RoboHelp X5 is a giant leap forward
in Help authoring technology, featuring Word 2003 support, Content 
Management, Multi-Author support, PDF and XML support and much more! http://www.macromedia.com/go/techwrldemo