I recently had a colleague submit to me a requirements specification that, 
IMHO, went too much into design.

My model of the world is that there are (a)requirements, (b)software design, 
and (c)test cases; and that (a) is very traceable to (c), perhaps even using 
a database product of some kind.

My boss' model of the world is very similar.  He indicated to me that his 
model of a requirements specification is mostly text, carefully indexed, 
about what the product must and must not do.

Questions:

a)Are there different models of the world?  What is a requirements 
specification?  What should or should not be in it?

b)Any book, paper, or tool recommendations?

c)Any other thoughts?

Thanks, Dave Ashley
-- 
David T. Ashley              (d...@e3ft.com)
http://www.e3ft.com          (Consulting Home Page)
http://www.dtashley.com      (Personal Home Page)
http://gpl.e3ft.com          (GPL Publications and Projects) 

David T. Ashley wrote:
> I recently had a colleague submit to me a requirements specification that, 
> IMHO, went too much into design.
> 
> My model of the world is that there are (a)requirements, (b)software design, 
> and (c)test cases; and that (a) is very traceable to (c), perhaps even using 
> a database product of some kind.
> 
> My boss' model of the world is very similar.  He indicated to me that his 
> model of a requirements specification is mostly text, carefully indexed, 
> about what the product must and must not do.
> 
> Questions:
> 
> a)Are there different models of the world?  What is a requirements 
> specification?  What should or should not be in it?
> 
> b)Any book, paper, or tool recommendations?
> 
> c)Any other thoughts?
> 
> Thanks, Dave Ashley

Well, I've written a few specs, including requirements and design.

A requirements spec, as you note, should state clearly [1] what the 
product should and should not do. It should not dictate the design in 
any way. In a sense, it is rather like the difference between an 
algorithm and an implementation; the algorithm specifies what is to be 
done, but in no way specifies the language or the specific 
implementation, although an algorithm is more design than requirements.

[1] A good requirements specification should be readable by multiple 
engineers who will agree, to the last dotted i, as to what it means.

Cheers

PeteS

David T. Ashley wrote:

> I recently had a colleague submit to me a requirements specification that,
> IMHO, went too much into design.

There are some who do this sort of thing and I have more often than not
ended up shredding such documents. One I had the misfortune to receive was
so large (greater than 400 pages) and so full of conflict that no sense
could be made of it. Having disposed of it I asked the client what his aims
were. The document that ended up as a statement of requirements was a mere
35 pages and included all that was needed.
 
> My model of the world is that there are (a)requirements, (b)software
> design, and (c)test cases; and that (a) is very traceable to (c), perhaps
> even using a database product of some kind.

I'd go a few more steps:-

  The initial kick-off is the clients concept description. This may be
included in his requirements document but should only state what the system
goals are and place those goals within the proper context of the systems
environment.

Next comes the Analysis phase:- Task Analysis, Hazard Analysis etc.

Only then should a Technical Specification be constructed which describes
the structure of the solution and the design ideas that would support that
structure. After this you are into detailed design in parallel with which
you should be constructing the test plans. Everything begins to come
together at, your carefully planned, integration phase where the test plans
come into play to prove what needs proving about the quality and
dependability of your system.

Of course, each of these stages can be split hundreds of ways but that is
the basic framework. Mixed with decent document control and configuration
management it should keep your development head straight.
 
> My boss' model of the world is very similar.  He indicated to me that his
> model of a requirements specification is mostly text, carefully indexed,
> about what the product must and must not do.
> 
> Questions:
> 
> a)Are there different models of the world?  What is a requirements
> specification?  What should or should not be in it?
> 
> b)Any book, paper, or tool recommendations?
> 
> c)Any other thoughts?
> 
> Thanks, Dave Ashley
> --
> David T. Ashley              (d...@e3ft.com)
> http://www.e3ft.com          (Consulting Home Page)
> http://www.dtashley.com      (Personal Home Page)
> http://gpl.e3ft.com          (GPL Publications and Projects)

-- 
********************************************************************
Paul E. Bennett ....................<email://p...@amleth.demon.co.uk>
Forth based HIDECS Consultancy .....<http://www.amleth.demon.co.uk/>;
Mob: +44 (0)7811-639972
Tel: +44 (0)1235-811095
Going Forth Safely ..... EBA. www.electric-boat-association.org.uk..
********************************************************************

> a)Are there different models of the world?  What is a requirements 
> specification?  What should or should not be in it?

I doubt there are different models.  Of course there are different document 
formats to describe requirements.  In my view, a requirements document 
should be limited to requirements (the strict definition) and not design. 
Mastery of the language used by the reader and writer is of utmost 
importance.

> b)Any book, paper, or tool recommendations?

A book I refer to occasionally is "Software Requirements" (2nd edition) by 
Karl Wiegers

> c)Any other thoughts?

Yes, the rule is "All requirements shall be unambiguous and testable."

The substandard requirements document that you described is often a product 
of inexperienced preparers.  I suggest you diplomatically coach the preparer 
in rewriting it with you holding his hand.  If a requirements document is 
faulty, the product will be faulty (garbage in - garbage out).

JJS

On Jun 20, 2:41 pm, "David T. Ashley" <d...@e3ft.com> wrote:
> I recently had a colleague submit to me a requirements specification that,
> IMHO, went too much into design.

One of the reasons fundamentalist bureaucratic structures do not
generate product designs either swiftly or effectively is because they
are too keen to assign black and white labels to particular spots of
gray.

Sometimes - mostly, perhaps - a requirements specification should be,
as you state, a list of what the product should and should not do.
However, in many cases this can mean a bit-and-microsecond-level
definition of the communications protocols it will speak.

Further, in some cases, a well-written requirements spec will mandate
the use of specific hardware design elements. For example, the right
radio transceiver for product A (volume 10k/yr) might be overkill for
product B (volume 1M/yr), but the economies of scale might be such
that the profitability of A+B together will be greater if both
products use the same transceiver chip.

Sometimes, over-engineering a product today may be a prudent move
because it will shorten the approval cycle for an on-the-horizon-but-
not-quite-here-yet change in some required type approval (I'm thinking
here of slow-moving, immensely stultifying standard-generators like
UL).

It all depends on the person generating the spec - how much visibility
of the "big picture" he or she has, and how much skill he or she has
in using that big picture. Theoretically, marketing has a much bigger
strategic picture of a product line than engineers making tactical
decisions; therefore in theory they are in a position to make some
intelligent decisions that superficially appear

(Yes, such people are rare. But I'm challenging your absolutist
viewpoint at an abstract level, not trying to convince you that it's
the wrong viewpoint for your specific organization).

>> I recently had a colleague submit to me a requirements specification 
>> that,
>> IMHO, went too much into design.
>
> One of the reasons fundamentalist bureaucratic structures do not
> generate product designs either swiftly or effectively is because they
> are too keen to assign black and white labels to particular spots of
> gray.
>
> Sometimes - mostly, perhaps - a requirements specification should be,
> as you state, a list of what the product should and should not do.
> However, in many cases this can mean a bit-and-microsecond-level
> definition of the communications protocols it will speak.
>
> Further, in some cases, a well-written requirements spec will mandate
> the use of specific hardware design elements. For example, the right
> radio transceiver for product A (volume 10k/yr) might be overkill for
> product B (volume 1M/yr), but the economies of scale might be such
> that the profitability of A+B together will be greater if both
> products use the same transceiver chip.
>
> Sometimes, over-engineering a product today may be a prudent move
> because it will shorten the approval cycle for an on-the-horizon-but-
> not-quite-here-yet change in some required type approval (I'm thinking
> here of slow-moving, immensely stultifying standard-generators like
> UL).
>
> It all depends on the person generating the spec - how much visibility
> of the "big picture" he or she has, and how much skill he or she has
> in using that big picture. Theoretically, marketing has a much bigger
> strategic picture of a product line than engineers making tactical
> decisions; therefore in theory they are in a position to make some
> intelligent decisions that superficially appear
>
> (Yes, such people are rare. But I'm challenging your absolutist
> viewpoint at an abstract level, not trying to convince you that it's
> the wrong viewpoint for your specific organization).

You make a very good point.  BUT! The "big picture" guy writing the 
requirements doc has failed to convey (write) the requirements if he doesn't 
state what the big picture is.  Just knowing the big picture doesn't excuse 
anyone from communicating it.

_All_ requirements are derived from upstream requirements.  The big picture 
needs to be stated or referenced in a requirements doc.

JJS

David T. Ashley wrote:
> I recently had a colleague submit to me a requirements specification that, 
> IMHO, went too much into design.
> 
> My model of the world is that there are (a)requirements, (b)software design, 
> and (c)test cases; and that (a) is very traceable to (c), perhaps even using 
> a database product of some kind.
> 
> My boss' model of the world is very similar.  He indicated to me that his 
> model of a requirements specification is mostly text, carefully indexed, 
> about what the product must and must not do.
> 
> Questions:
> 
> a)Are there different models of the world?  What is a requirements 
> specification?  What should or should not be in it?
> 
> b)Any book, paper, or tool recommendations?
> 
> c)Any other thoughts?
> 
> Thanks, Dave Ashley


IMO the requirements can be anything from definition of inputs and
outputs leaving you flexibility in the design to very detailed spec
choosing algorithms (e.g. telecom specs).

I would not get hanged-up on models. Customers have right to choose as
much detail as they want. You have the right to come back and tell them
it's garbage.

Personally I cannot stand vendors convincing me that I need something,
when in fact I clearly communicate my requirements and they still end up
delivering something they can do rather something I need (this whine is
about my interractions with web-designers few years ago, which made me
to look into things and become one myself to get my own stuff done).

Just reminded me a part of Family Guy where Peter needs money for his
boat to become fisherman and comes to one-man bank, gets the money, then
banker goes into next room and turns into tatoo artist asking the
customer what tatoo he wants:

  - I want a skull
  - Are you sure? How about Kermit the frog?
  - No, I want a skull.
  - Ok then. I am going to go ahead and do Kermit the frog.

--
Roman
www.dipmicro.com

On Wed, 20 Jun 2007 14:41:17 -0400, David T. Ashley wrote:

> a)Are there different models of the world?  What is a requirements 
> specification?  What should or should not be in it?

Some time ago I came across a nice diagram in a book that graphically
showed four classifications of 'perceived' requirements as (iirc):

(1) functional requirements 
(2) non-functional requirements 
(3) design aims
(4) design decisions

with (4) being highlighted as *not* belonging in a requirements document,
and should be removed.

Some broadly regard user requirements specs just as functional and
non-functional requirements, but I probably prefer the four (really 
three) above. Some take it further - take a look at FURPS+, but that's
way too refined for me ;-)

With regards to world models the one I mostly have used (and expected to
use by most of my immediate superiors), is

(1) Some bloke says Paul, I want this ... and mostly explains general
concepts/aims, with some specific requirements

(2) I have a think about it......then 

(3) Document what I'm thinking in what I call a design document, which
basically consists of a few sentences of 'scope', a block diagram (i.e.
top level design (or architecture, if you prefer that phrasing)), for both
hardware and software 

(4) I might lash something up to verify software performance on a
particular processor, etc, i.e. address any risk areas before bulk of
design starts

(5) I progress the design, and on occasion talking to the bloke who asked
me for the design in the first place, whilst maintaining my design
document, with anything that I think I would like to remember (that is
reasonably high level), and know that I don't stand a chance of
remembering without writing it down. 

(6) I get everything going on prototype hardware, and test it and record
my results in a document 

(7) Another bloke then comes along and tests it. Sometimes a few
adjustments might need to be made. Other people do some things (I think!) 

(8) Shipped!! 

(9) Any improvements/changes/fixes - ie, some bloke (you guessed it), asks
me to change the design so that it does x as well as y, and this time
around, *really* does z 

In a formal process, you might have:

(0) Inception phase - i.e. document business case, main aims/requirements,
risk areas etc 

Substitute (1) above with: (1) I want what is outlined in document from (0) 

(2) do some requirements analysis - i.e. look at document from (0), and
get to a requirements spec 

Where hardware is involved you might have an A, B, and C model (I worked
on a project like this once) For software you might do some coding before
fully analysing requirements (ie agile process), or you might use a more
or less waterfall style development process, which works just fine for
most embedded projects.

I remember reading somewhere that some software consultancy used an agile
process for a safety critical design successfully - Can't remember details
- should have written it down ;-)

For safety critical design you need to do certain things, other than just
get something working. But I haven't worked in this environment, so
couldn't comment further.

> b)Any book, paper, or tool recommendations?

I have read a few books (sadly) on development processes, and I guess I am
a bit reluctant to make make any recomendations, because most of what I
have read is shite :-), imho, of course. And, ironically, the stuff I
have written in this reply has just added to the general body of it :-)

But I guess I would recommend Craig Larman (applying uml and patterns, a
design guide to OOA/OOD & iteratative development) (www.craiglarman.com/),
although orientated towards larger software systems (which might not be
what you want), but he does at least seem to write honestly, rather than
focusing on selling you some whizzo development process.

From the book, he is thorough and his rationales are good. I like use
cases (although use case diagrams are a waste of time if you spend more
than 10 minutes on them). Most of the UML I find a complete waste of time,
but YMMV. I did like reading about the unified process, and its phases -
makes a lot of sense for larger bits of software. Generally a good book on
software process, certainly the best I have seen. 

HTH

Paul Taylor

"David T. Ashley" <d...@e3ft.com> wrote in message 
news:i...@giganews.com...
>I recently had a colleague submit to me a requirements specification that, 
>IMHO, went too much into design.
>
> My model of the world is that there are (a)requirements, (b)software 
> design, and (c)test cases; and that (a) is very traceable to (c), perhaps 
> even using a database product of some kind.
>
> My boss' model of the world is very similar.  He indicated to me that his 
> model of a requirements specification is mostly text, carefully indexed, 
> about what the product must and must not do.
>
> Questions:
>
> a)Are there different models of the world?  What is a requirements 
> specification?  What should or should not be in it?
>
> b)Any book, paper, or tool recommendations?
>
> c)Any other thoughts?
>
> Thanks, Dave Ashley
> -- 
> David T. Ashley              (d...@e3ft.com)
> http://www.e3ft.com          (Consulting Home Page)
> http://www.dtashley.com      (Personal Home Page)
> http://gpl.e3ft.com          (GPL Publications and Projects)
>
You might try looking at IEEE 830-1998  Recommended Practice for Software 
Requirements Specification.  You can find it on the web.

Scott