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.
>From techwr-l -at- listserv -dot- okstate -dot- edu Tue Apr 14 12:52:43 1998
>Received: from listserv (139.78.114.100) by listserv.okstate.edu (LSMTP
for Windows NT v1.1a) with SMTP id <1 -dot- 4012D740 -at- listserv -dot- okstate -dot- edu>;
Tue, 14 Apr 1998 14:54:39 -0500
>Date: Tue, 14 Apr 1998 12:46:09 -0700
>Reply-To: Richard Cook <Cook-Richard -at- CDSSOFTWARE -dot- COM>
>Sender: "Technical Writers List; for all Technical Communication
issues"
> <TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU>
>From: Richard Cook <Cook-Richard -at- CDSSOFTWARE -dot- COM>
>Subject: SOFTWARE PRODUCT SPECIFICATION
>To: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
>
Richard Cook wrote:
>I need to create detailed specification documents for a set of software
>applications. Anybody have a format guide or template that would be
good
>for this? Ideas or input also welcome. Thanks.
>
Richard:
The primary task in creating detailed software requirements
specifications is to obtain a clear and concise understanding of what
the requirements are. Experts such as Yourdon and Associates state that
this is 98% of the required work.
There is only one true way of obtaining such an understanding. That is
to utilize of structured systems analysis techniques when performing
your analysis. These are data flow diagrams, entity relationship
diagrams, data dictionaries, and mini-specs.
Why these specific techniques? Because the essence of a requirements
specification is a detailed statement of WHAT the software must do (from
the end user's viewpoint). The above mentioned techniques are the only
tools that enforce a rigorous systematic analysis of the WHAT. There
are no other.
It is a very common mistake for specification creators to forgo
obtaining a rigorous understanding of WHAT the system must do uitilizing
structured systems analysis techniques. The results are very
predictable. They are:
a.) A lot of "holes" in the specification's logic (i.e. the whole
thing just does not tie together).
b.) A focus on HOW the software will work. The HOW
description is a design document - not requirements specs. As
a requirements spec, these documents are not worth the paper
they are printed on.
After you have first "nailed down" the requirements using structured
systems analysis techniques, it is OK to then translate them into text.
In fact, from significant experience doing such, I can say that the task
of then creating text based documentation is easy. You will not need
any more techniques - the approach will be intuitive.
