Thoughts on the Purposes of Writing a Requirements Specification

The purpose of these deliverables is to try to build up your understanding of the system piece by piece until you are able to put all the pieces together to put together a coherent specification of the system. If you were to try to do it all in one big bang, it would be overwhelming, such as trying to write the software in one big bang :-).

For the first deliverable, you will model the system from one viewpoint and learn what you can from it. You will get feedback from your TA on that model with suggestions for improvement, and you will revise the model based on the feedback. For each of the next two/three deliverables, you will model the same system from another viewpoint. As you do so, you will find that doing so exposes problems in your previously delivered models. You will have to revise all prevously delivered models to be consistent with the new model you are preparing for delivery, so that you can deliver all of them as a constitent whole.

As you deliver in any deliverable, you must hand in also all previously delivered deliverables, updated to take into account all feedback you have gotten from your TA and to be consistent with the current deliverable. You will be building, deliverable-by-deliverable, an ever-growing, but self-consistent model of what your project will look like!

This way you will be building up slowly the information you need to do the first draft of the final deliverable. Leaving out any early deliverable, even one whose model does not say anything beyond the obvious, makes doing the final deliverable or its draft much harder because you will have lost the opportunity to work out these small picky inconsistencies that always exist between what the omitted model would say and the other more critical models. The reality is that often lurking in those so-called obvious things that don't need to be said are little details that people disagree on, but don't know that they do, or that give rise to picky picky exceptions that bring a system crashing down.

So please do ALL the deliverables even the ones that don't see are going to say anything new. At the very least, you will now have all this obvious stuff written down where everyone can see it and agree that it reflects his or her understanding. If indeed it turns out in the end that the deliverable didn't tell you anything you did not know, never participated in exposing a problem, and never needed to be changed, the you have gained the knowledge that the information of the deliverable is stable and there will be no surprises coming from its direction :-).

In any case, for any system, it is impossible to predict up front which of the models will be useful and which will not. So the course requires that you do all of them, just in case.

If You Have Already Started Implementing

If your team has started implementating already, then do not specify what you have implemented (aw! shucks!). Instead, specify the system that you and your customer had in mind when you wrote and refined your project's abstract that is at the repository. Remember, that at the time, you got your customer's buy-in to this intent. So he or she is expecting something similar to that intent.

In particular, it is not acceptable to produce a specification that is built from your implementation upward.

"Why," you ask, "should we ignore what we have done?" Because, the prof wants you to see if what you have implemented meets your own intent. If we don't know what the intent is, we cannot do that comparison. Also, he believes that you will still learn something useful, if not for the current version, but for the next.

"But, what we'll produce will bear no relation to reality and will have to be thrown out." OK, that's fine by the prof. Remember, SE 463 is separate from SE 490. It has its own objectives. If achieving these objectives helps your capstone advance, that's fantastic!!!!!. But if not, then so be it. It's more important that the objectives of SE 463 be achieved than that its project helps your capstone. So, to get a decent grade in SE 463, you will have to play along with the prof's game, to humor him and live with a useless project. After all, if the project were as it used to be, writing the specification of a concocted system, the result will for sure be useless. At least this time, there is a chance that the project of SE 463 will not be useless.

A Rough Spec?

A rough specification is not enough. It's too easy to handwave in a rough specification, but handwaving in code is impossible without making the code not work. That's why you discover flaws (D reqs) during coding. A rough specification that is too rough is hand wavy and does not force thinking about the D reqs. It's got to be pick-picky enough to dislike doing it, for you not to be able to handwave anything about it :-(.

Not All Deliverables Are Valuable

Not all deliverables will be equally valuable to your group, i.e., one or more may tell you nothing that you don't already know. Even so, as you work on it or try to make it consistent with the others, you may discover something you don't know. In the end, even if you don't discover something new, you've confirmed that what you thought you knew is indeed what you know and all you need to know :-).