re: where do docs fit in the development process?

["Christensen, Kent" <lkchris -at- sandia -dot- gov>]

re:  ... some *big* mistakes that should have been caught, ppl were very
nonchalant about it.

Many will be happy to know that in the USA nuclear weapons process, once the
documentation draft is completed ...

1.  it is reviewed by a group of design lab engineers (and other politicians
from the labs) in a formal session where every word of the manual is read
aloud and procedures are performed as written

2.  following changes from the first meeting, the same excercise is repeated
in the presence of the military customer where the military customer reads
and performs the steps.

While we have the "advantage" that use of the manual is always required when
our products are used or maintained and only procedures listed in the manual
are permitted and the manual must be read step for step by someone
supervising those performing ...

... the conclusion I offer is that your group still needs "testing" of the
documentation with as real "users" as you can muster.  Make the process one
where the documentation is followed as written.  Have your design engineers,
programmers or whatever present to view how users actually relate with your
product.  Here, all this is naturally considered part of the
design/development process, but more important is the concept of doing
independent testing.  I don't see how any tech writer can do without it, and
don't think it has to be too difficult.  Neither does this guy:
http://www.useit.com/alertbox/20020120.html

If your firm won't do documentation testing, here is the story:

Your developers very likely expect you to understand your firm's products
and to be able to write an accurate manual.  They do not necessarily
perceive it their job to validate the documentation--in the long run your
tech support department will provide that service by providing you
frequently asked questions.  Your job, outside and in addition to producing
documentation, is to learn how your products work and to test your
documentation yourself.


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