Help requested re software specifications?

[Geoff Hart <ghart -at- videotron -dot- ca>]

Bonnie Granat wondered: <<I have never written software specifications 
of any kind. A prospect has inquired about my availability to help with 
his company's specifications and user documentation. My Internet 
research tells me that there are several flavors of software 
specifications...>>

Doesn't much matter what the various flavors are: the important 
question is what specifically your potential client want you to 
produce. Once you know that in detail, you can make an informed 
decision about whether you feel you can learn to do this on the fly. 
Find out, and write back to us with specific questions. In the 
meantime, points to ponder:

<<It seems to me that these documents are company-specific and that 
there are no widely recognized standards. I have seen examples of the 
above documents and have reviewed some pertinent Web sites...>>

Exactly right: some software developers claim to be "engineers", but as 
an industry, have yet to develop a standard code of practice and 
standard for excellence and professional responsibilty that a real 
engineer would respect. There's still far more art than science in 
software development.

Even if you could find a standard, your research has clearly 
demonstrated that there are many different and probably incompatible 
possibilities. This isn't a problem if you have a client willing to 
work with you to define:
- what objectives they hope to accomplish with the specifications
- who will be using the specifications

Combine these two bits of information and you can work with the users 
of the specs to determine exactly what they need, and in what format, 
to meet their objectives. The actual task won't be as simple as that 
description makes it sound, since you're dealing with people rather 
than abstractions, but really, this isn't rocket science: like any 
other form of good technical writing, it involves building a bridge 
between the users of your docs and what they hope to achieve. That's 
what we do, no?

<<What I am not clear on is whether I ought to say to this prospect 
that I can do his documents, or whether I actually need to have 
experience creating them.>>

If they want you to produce something to MILSPEC or ISO 1234* or any 
other standard, with the output quality judged by some regulatory or 
official body, then you need to make it very clear that you don't have 
experience with that standard. That doesn't mean you can't try to learn 
the standard on the job if they're willing to wait while you pass 
through your learning curve. But if there isn't any formal spec they 
want you to adhere to, treat it like any other job: you'll learn the 
subject and the audience as you go.

* Which, amusingly enough for a number typed at random, turns out to be 
an actual ISO standard (for split pins).

--Geoff Hart   ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

SEE THE ALL NEW ROBOHELP X5 IN ACTION: RoboHelp X5 is a giant leap forward
in Help authoring technology, featuring Word 2003 support, Content 
Management, Multi-Author support, PDF and XML support and much more! http://www.macromedia.com/go/techwrldemo