Requirements Specification? Requirements Management?

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.

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.

--
********************************************************************
Paul E. Bennett ....................
Forth based HIDECS Consultancy .....
Mob: +44 (0)7811-639972
Tel: +44 (0)1235-811095
Going Forth Safely ..... EBA. www.electric-boat-association.org.uk..
********************************************************************

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.

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

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

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).

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

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

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

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.

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 s**te :-), 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)

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

You might try looking at IEEE 830-1998 Recommended Practice for Software Requirements Specification. You can find it on the web.

Scott