Subject: philosophy behind the orange requirements document
From: brlewis@MIT.EDU
Date: Tue, 11 Apr 95 18:24:35 -0400
To: orange@MIT.EDU

It has been extremely helpful to have the two-day (1.5 day?) deadline
for comments, because I've been able to go through them all and get an
understanding of the kinds of issues that will be brought up at the
review.

I think some explanation of the thought processes of the Orange team
would make the document much more understandable, so I'll try to
summarize the reasoning behind its overall structure and content.

STRUCTURE

We encountered a bootstrapping problem:  How are we supposed to decide
how to structure our requirements document before we write guidelines
for writing requirements documents?

We chose to go with the IEEE standard structure (cited in the reqs doc).
This specifies the contents of sections 1.1-1.5 and 2.1-2.5 number by
number.  We chose to include section 2.4 in order to adhere to the
standard.  It's like "this section intentionally left blank," or, "this
section left blank because ....".

Some people may like definitions, etc. in an appendix.  Some may like
them up front.  If a standard outline is followed, people can easily
skip around in whatever order is most comfortable to them.

The titles of section 1.1-1.5 are straight out of the IEEE spec.

CONTENT

Sometimes it's hard to distinguish requirements from design.  When
you're writing requirements for a document, it's even hard to
distinguish requirements from implementation.

Here's how we thought about it:  As customers, if we were to hand this
requirements document off to someone else to implement, would this be
true....?

	design consistent with requirements <--> we like it

I.e., there might be many designs for a development process that we
would be content with, and many we would dislike.  An ideal requirements
doc divides designs we would like from those we would dislike.  How good
a job we did will be discussed at the review.

Orange team, please feel free to add to what I've said.