Re: how long Requirements

["Simon North" <north -at- synopsys -dot- com>]

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