Help requested re software specifications?

Subject: Help requested re software specifications?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 03 Jun 2004 21:40:21 -0400

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!

From a single set of Word documents, create online Help and printed
documentation with ComponentOne Doc-To-Help 7 Professional, a new yearly
subscription service offering free updates and upgrades, support, and more.

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 for more resources and info.

Help requested re Software Specifications: From: Bonnie Granat

Previous by Author: Contract-to-hire pricing?
Next by Author: Upload/download terminology?
Previous by Thread: Re: Help requested re Software Specifications
Next by Thread: Re: Help requested re Software Specifications

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

Sponsored Ads