Specs from Heaven

[Garret Romaine <GRomaine -at- MSMAIL -dot- RADISYS -dot- COM>]

Earlier I asked what a technical writer is looking for in a specification.
While there were some responses along the lines of "how nice, a spec to work
from," and I feel for you, those of us who have had to "ISO up" are a little
further along. Since I expect to soon be able to sign off (and, by
definition, refuse to sign off) on hardware and software specifications, I
developed the following list (with special thanks to John Oriel, Robbie
Rupel, and Ed Hoornaert). Sorry for the length, and all my cool formatting
from Word for Windows was lost;  also, there are some specific issues to my
company, but I think you can get the drift:

++++++++++++++++++++++++++++++++++++++

What does a technical writer require from a spec?
Software
? Flow. Flow from screen to screen. In order to write a user s manual from a
software spec, I need to be able to follow the flow of a function or group
of functions. This should include each prompt and a general discussion of
each possible response.
? Screen layouts. A screen shot of the user interface is important, even if
it is just a proposal.
? Setups. Installation and setup concerns are very important. Operating
system limitations are nice to know. Known incompatibilities and
inconsistencies should be noted. In the case of updates to existing
software, a bulleted list of proposed changes is extremely important.
? File names. Whenever new software programs are required, it is important
to be able to write the name(s) of the software and the total number of
diskettes that will ship with the product can really help.
? Error recovery. A complete list of error messages and proposed workarounds
is very important.
? Level of detail. If you err on the side of including information, you
decrease the amount of time I have to spend interviewing.

Hardware
? Environmentals.  Environmentals should be thought through, and not just
cut-and-pasted. An estimate should be used for current and power, with a
note that the final answer will be calculated. I am constantly chasing this
information down until the last minute.
? Non-standard areas. Any areas where the product does not emulate a
standard IBM PC/AT product should be noted and explained. Any strange
methods of emulating standard PC/AT products should be noted.
? Chip sets. Chip sets should be listed. Port addresses and IRQs should be
noted. Memory maps, DMA info., etc. should be explained.
? Option byte setups. The standard OB1 and OB2 configuration should be
listed. The defaults should be noted. Known conflicts with other IRQs, port
addresses, base addresses, etc., should be thought out.
? Connectors. Front panels and connectors should be documented in detail;
 pinouts, gotchas, etc. Any special cables should be explained.
? Graphics. A graphic showing the layout of the board really helps.
? Jumpers. Any and all jumpers that will survive the manufacturing process
should be depicted and explained fully, for my purposes. I imagine that the
spec would be the only place to document jumpers and headers used
exclusively by manufacturing or testing.
? Theory of Operations. A theory of operations paragraph is required to
provide a level of detail engineers need to use the product. They also
require information about the programming interface.
Other
? Sign-off and stick to it so that nothing major changes without my knowing
about it.
? Define the customer and explain who the audience is.

See:  Requirements Engineering, Goguen and Jirotka