Re: how long Requirements

Subject: Re: how long Requirements
From: "Simon North" <north -at- synopsys -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Sat, 8 Apr 2000 21:56:08 +0200

Without intending to pick an argument with Tony Markatos, from
my own experience as a software QA engineer, I can think of at
least 15 different sorts of software spec.

Without going into all the gory details, a spec should reflect what
you intend to do with it. Just like any other document, it has an
audience and a purpose. Customer/end-user specs are usually
functional specs, aimed at showing the end user what she will get
and/or ensuring that the software does what is agreed.
Approaching from the other end of the spectrum, you can have
detailed implementation, interfacing and test specs (these are
common in defense circles where each sub-division of the top-level
software creates a branch of lower-level spec documents).

The most common form of spec you will find in non-defense circles
are functional specs. They describe the behavior of the end
product. Their length varies according to the complexity of the
product, and they should be as long as needed to explain what the
product does (is supposed to do). They may or may not contain
detailed data (this depends mostly on the development philosophy,
requirements-based/design-for-test activities tend to increase the
amount of actual physical data included).

I have only very rarely seen a spec that contained NO text. I have
seen specs that used a lot of dataflow diagrams (mostly extracted
from case tools), but even then there is about 10% additional text.

In defense circles specs are generally massive (I worked on one for
a tactical command system whose top-level functional spec was
over 500 pages long. The software had 2.5 million lines of code and
we estimated that there was approximately one page of
specification documentation PER line of code.) and take on an
importance of their own. In these developments, the customer is
commonly allowed access to the specs and they provide a visible
guarantee that the product not only does what it should, but also
that it was built properly and can be maintained for its full lifetime
(sometimes in excess of 50 years).

In commercial environments, specs are more internally focused,
documenting the main characteristics of the software, acting as a
record of design decisions, trade-offs, and so on, that give the
software developer enough information to be able to start work (in
these cases the spec is often incomplete and ultimately does not
always reflect the final product as they aren't always updated). In
many cases I have simply seen the 'spec' used as sort of white
paper. The developer (a team member) writes down what she
intends to create, the team discuss and agree, and the developer
goes away and builds it. Two (HTML) pages is often enough for a
simple piece of software such as a text editor.

This is all opinion based on experience of course, your mileage
may vary.

Simon North
Senior Staff Technical Writer,
Synopsys, System Level Design R&D




Previous by Author: Article: Converting FrameMaker's Help Files to PDF
Next by Author: FrameMaker and Grammar checking
Previous by Thread: Re: how long Requirements
Next by Thread: www.NotHarvard.com?


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


Sponsored Ads