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.
Subject:Working from engineering specs From:Kat Nagel/MasterWork <katnagel -at- EZNET -dot- NET> Date:Fri, 1 Dec 1995 13:56:40 -0400
Suzanne Pyle asked:
>My question involves using engineering specs to write the manual.
>Have any of you done this before without actually using the
>software/hardware?
Yes. <sigh> Oh <insert your deity of choice>, yes!
It's possible, maybe even reasonable, to write a -first- draft from the
engineering specs. But I will scream like h*** if another client expects
me to produce the -final- documentation that way.
[SOAPBOX mode = ON]
[VOICE mode = Voice of Experience]
The software product that is shipped to customers NEVER exactly matches
the specs. Even if the programmers did a terrific job of planning before
they started writing code --- even if they periodically revise the specs
along the way --- they ALWAYS add little refinements or change details
here and there to solve problems. The real product ALWAYS has significant
differences from the specs. These are confusing to the user if they aren't
documented properly.
Get hold of a prototype of the program as soon as it's available, even if
the engineers say "it isn't final yet." Beg. Plead. Bribe them with
cookies.
Talk to the engineers. Ask them what features they're working on.
Talk to the QC folks and beta testers. Get copies of their bug reports.
Find out what changes the engineers are making to fix the bugs.
Give your first draft to everyone who is working with the prototypes, and
ask them what's wrong with it. Pay attention to their answers.
Get copies of each and every software update as soon as it's released from
the programmers to the quality control staff, and repeat the process.
If you can't run the software on your own computer, arrange to go to their
site for a day or so to play with each new version. Go in at night or on
weekends, if you have to. It's worth it. Honest.
Get yourself invited to the sessions where they train their sales staff.
Ask them to use your most recent draft for the training session. Take
detailed notes whenever anyone complains about it.
And GET YOUR HANDS ON THE VERSION THAT SHIPS. Even if you don't
have time to rewrite the manual to match the final version, you can at
least write a Read-This-First letter that can be stuffed in the box to
alert customers to "new features added after the manual went to press."
The customers will thank you.
The guys that staff the customer service hot-line will thank you.
Eventually, the person who signs the checks will thank you.
[VOICE mode = return to Default]
[SOAPBOX mode = OFF]
K@
Kat Nagel________MasterWork Consulting Services
LIFE1(techwriting/docdesign) katnagel -at- eznet -dot- net
LIFE2(vocal chamber music) PlaynSong -at- aol -dot- com
"Would you mind stepping outside
while we tear your proposal to shreds?"
---------New Yorker cartoon, 11/13/95
