Working from engineering specs

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

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

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.

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]

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

Previous by Author: Boring Discussions/Setting Expectations
Next by Author: Re: Managing diagrams & screen shots for paper/online
Previous by Thread: Re: Proper use of commas in
Next by Thread: SUMMARY 2: HTML products

What this post helpful? Share it with friends and colleagues:

Sponsored Ads