Help spec'ing quality (validation/testing) of documentation?

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

julie brodeur reports: <<I work [with] about 15 system administrators, who
have, until recently, written their own documentation (usage notes in HTML)
and posted it to their intranet. The problem with this is that there was no
quality control for testing the procedures that the sys admins wrote, and no
one to follow up on missing information.>>

In your original message, you noted that there are really two problems to
solve: first, getting the information up on the intranet immediately so that
people can use it, even if it's incomplete or partially inaccurate, and
second, making it usable (editing, quality control, and identifying missing
information). Where inaccurate or misleading documentation might cause
serious problems (e.g., crashing the network), the first criterion may have
to be sacrificed in the interest of safety, but that's a management
decision: either they want quality control before a document goes live, or
they're prepared to live with the problems that may result.

One thing that might work is to develop a cooperative approach to creating
the documents. For example, some of my authors have occasionally had enough
difficulty producing a good first draft that I sit down with them and write
the manuscript--or else they dump all the data on me and have me write it
without their assistance, and they review it when I'm done. Given that
they're already having trouble with the writing, this often saves them
considerable time (the document gets written faster) and also saves me time
(it gets written better and requires less editing). Worth looking into?

It seems to me that you can solve both problems using a two-stage approach:
As soon as a document is ready, the author sends it to you for posting on
the intranet. Posting it immediately, perhaps after a cursory edit to detect
any really serious problems, makes the information immediately available.
Once the document is posted, you can then schedule time to edit and test the
documentation. If authors indicate the criticality of a document when they
send it to you, that would help you determine whether it's a "drop
everything else and do it now" edit, or something you can do when time
permits. That's more or less the way we're headed with our own nascent
intranet.

One thing you might want to investigate is developing templates that make
the author's work easier, and thereby help ensure a more efficient
development process: by getting the right information in the first place,
you no longer have to obtain it or create it during editing. (A dream, I
know, but the goal is to head in that direction. We've gone quite far in
doing this with our technical reports, and entirely eliminated certain
classes of problem.) Of course, templates only work if there's some
consistency to the work your authors are doing; if each document is unique
and independant of all other documents, templates won't help.

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

Hofstadter's Law--"The time and effort required to complete a project are
always more than you expect, even when you take into account Hofstadter's
Law."

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Now's a great time to buy RoboHelp! You'll get SnagIt screen capture
software and a $200 onsite training voucher FREE when you buy RoboHelp
Office or RoboHelp Enterprise. Hurry, this offer expires February 28, 2002. www.ehelp.com/techwr

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