[prog] Passing data between modules

[Jimen Ching]

On Fri, 1 Aug 2003, Jacinta Richardson wrote:
>Standard document formats or not, writing your documents really does make
>life easier in the long run.

Yes, once everything is said and done, these documents will prove
themselves to be worth the effort.  But while you're knee deep in it, it's
hard to see the light at the end of the tunnel.

>     ----------------------------------------------
>
>     Remove Counsellor
>
>     ----------------------------------------------
>
>     When a counsellor is no longer working for AB they may be
>     removed from the system.  This may only occur if the counsellor
>     has no clients assigned to them.  If clients are assigned to a
>     counsellor a request will be issued that those clients be assigned
>     to someone else, or marked as unassigned.
>
>     Counsellor mailboxes and details are not deleted from the system
>     as a whole, but they will not show up when assigning clients or
>     viewing details.
>
>     --------------------
>
>Yup, fine, that describes what happens.  But how on earth do you test it?
>This is what it should have been:

It seems to me that this looks more like a System/Subsystem Specification.
I don't know if my employer made up this document format, but the SRS is
derived from the SSS.  Each requirement must be tracable back to an item
in the SSS.

>The problem was that we signed off on our tender document as an SRS
>because we were too busy to do the paper work and generate a proper SRS.
>This lead to us having a fairly different idea of important parts of the
>sytem than our clients had.  Even worse, it lead to important areas of
>the system being rather undefined!  We couldn't make a real design based
>on this crappy SRS so we did the SADD and went into the coding.  This
>was also a mistake, of course, as we have duplicate functionality in
>quite a lot of areas that should have been identified and put into
>libraries.  It also means that we don't have the best solutions for a
>lot of things, because I'll do things one way and then discover later
>that Paul did them a different, somewhat better way (or sometimes
>worse).

Hindsight is a great tool.  But it often comes after the fact.  I'm not
sure how you could have written the SRS differently to avoid the problems
you ran into.  Things like putting common code into a library can only
come from a complete design review.  The SRS usually doesn't cover the
details needed to identify the functionality that can be made into a
library.  I'm curious as to what you would've done differently.

>So rather than saying
>
>1.  The user interface is user friendly.
>
>you should say something like:
>
>1.  The user interface conforms to standard X for accessibility.
>2.  The user interface conforms to standard Y for accessibility.
>
>or whatever's appropriate.
>
>Anyway, the point was that even though writing the documentation took
>forever, well, a while, when it finally came to implementation all 11
>coders were very comfortable with what they had to write, what their
>interface had to include and how it came together.  Integration and
>testing was a breeze!

Have you heard of the DoD's Joint Technical Architecture (JTA)?  That's
basically the standard we need to conform to.  Believe me, that
specification doesn't help very much.  I came from a networking
background, so I've read lots of specifications.  If you've ever compared
the Asynchroneous Transfer Mode (ATM) Signaling specifications
(PNNI/B-ISUP) to IPv4 routing protocols (BGP/OSPF/etc), you'll understand
the wide range of standard specification document quality.  The ATM specs
are so thorough and complete, you can practically run a code generator
over the documents and produce working source code.  On the other hand, I
wouldn't call those documents describing the IPv4 routing protocols
'standard specifications'.  I'm surprised there's any interoperability in
those router equipments at all.

My concern is the situation where there is no standard to follow, and the
problem domain has so many variables, the SRS reads more like the theory
of black holes than a software requirements document.  To give you an
example.  Let's say you were given the project to develop a image sensor
device (basically a system to take pictures of stuff).  The problem is,
this is all you're given.  Some of the questions you might ask include:

1.  How many cameras are involved?
2.  What are the sizes (resolution) of the images.
3.  Will there be different color bands for different cameras?
4.  Do you need automatic scanning (be able to point the cameras)?
5.  When will the sensor be used, in sunlight, in moonlight, both?

The answers to these questions will determine your requirements.  But no
one knows the answers, because no one has created such a system before.
Also, the answer could put the design complexity off the scale.  Which
would cause the cost of the project to sky rocket and the duration of the
project to go on forever.  Of course, you don't have forever nor a
buttomless wallet.  So what do you do?

Of course, you could say--PROTOTYPE!  But that just begs the question;
does a prototype also need an SRS?  No matter what the answer is to this
question, you're either in the pan or in the fire.  You're still cooked.

--jc
-- 
Jimen Ching (WH6BRR)      jching at flex.com     wh6brr at uhm.ampr.org