TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Thanks to everyone who responded on the schedule development questions. Between this list and some input from my boss, I think I have all the holes covered.
Chuck Martin asked:
> So just a question that omes to mind: If you (just) test all the
>procedures that you've written, how do you know if you've written all
>the procedures.
>Reviews by SMEs can tell you "Oh, you can do this, this, and this too."
There were some other comments about this, off-list also. I realize nobody's losing sleep at night over my methods here, but I thought I'd add that in the interests of brevity, that one line about doc testing really left out a lot of detail.
But if I had said instead for that step "Validation/Verification in accordance with USAF TO 00-5-3" it wouldn't have been terribly clear to most people reading the message.
Here's our system in a nutshell:
In addition to myself and the two tech writers, the tech writing team also includes a full-time dedicated system engineer. Her job (and her -only- job) is to do desktop reviews of the procedures to ensure that they're accurate and complete. The two questions she has to answer are "Is what we wrote correct?" and "Did we leave anything out?"
Once she has completed her desktop reviews and we've incorporated her comments, we move on to the validation phase. That's where our organization (writers working with our base technicians and the systems engineer noted above) move into a lab and run through every single procedure, performing them on the actual hardware and software. When we find errors, we make the fixes, and then re-test the fixes to make sure they're right. (This phase is known as "validation" per 00-5-3.)
We then end up with a "final" version of the docs which we turn over to the customer (that is, the USAF). At an Air Force base, we tech writers show up and watch as a team of Air Force technicians then re-do what we did above. They perform every single procedure on the hardware and software. (This phase is known as "verification" per 00-5-3.) We sit there and take notes on changes that they want made, including the development and inclusion of any procedures that they feel are missing. When we leave we either have a detailed draft with specific information as to where it will be inserted, or we have agreed upon a change schedule and a date for updating the manual.
Yeah, the doc testing system here is fairly thorough. And even the paragraphs above really are just a brief description of what we do during the val/ver.
Shameless self-promotion: for more details on how it's done, those who have access to the STC website can look up a paper I wrote that is in the proceedings for the 2003 (Dallas) conference. The "lite" version is the PPT slides, here:
ROBOHELP X5: Featuring Word 2003 support, Content Management, Multi-Author
support, PDF and XML support and much more!
TRY IT TODAY at http://www.macromedia.com/go/techwrl
WEBWORKS FINALDRAFT: New! Document review system for Word and FrameMaker
authors. Automatic browser-based drafts with unlimited reviewers. Full
online discussions -- no Web server needed! http://www.webworks.com/techwr-l
---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -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.
