[prog] Passing data between modules

[Jacinta Richardson]

On Wed, 30 Jul 2003, Jimen Ching wrote:

> What I would like to know is, are there any anecdotes that show these
> documents actually improve the development process?  One of the problems
> I'm beginning to see is that these documents assume the problem domain is
> well understood.  This is fine, if it was true.  But my employer is in the
> research field.  Which implies that not everything is well well
> understood.  How effective is a requirements specification if the
> requirement is not well understood?
> 
> Can you share some of your experiences with these standard document
> formats?

Standard document formats or not, writing your documents really does make
life easier in the long run.  So I'm very happy to give a story or two...

We'll start with a kind of recent one.  Perl Training Australia used to
exist of just my fiance and myself, and I didn't work that many hours for
it.  A client of ours, who'll we'll call AB from now, asked us to quote on
a project and sent us various odd pieces of documentation.  I helpfully
wrestled the documentation into a description of the system they wanted
and made what I'd call a tender document.  The quote was accepted and work
commences renaming the tender document as an SRS and
_getting_the_client_to_sign_off_on_it_as_such!

If you are a software engineer you're probably cringing at this point.  So
you should be.  So should we have been.  But I was too busy at the time to
notice.

For non-software engineers I'll give you an example.  This is what the
tender document said for a small section:

     ----------------------------------------------

     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:

     -------------------------------------------------
     Remove Counsellor
     -------------------------------------------------
     From time to time the AB Administrator will need to retire and
     remove counsellors from the AB system.  The following
     requirements relate to this process.

     1.  There exists a method by which the administrator can remove a
         counsellor from the system.
     2.  Counsellors can only be removed from the system if they have
         no clients assigned to them.
     3.  It is possible to move all clients from one counsellor to
         another.
     4.  It is possible to move all clients from one counsellor to
         being unassigned.
     5.  Removing a counsellor does not delete their mailbox and
         folders.
     6.  Removing a counsellor does not free their username for
         someone else to use.
     7.  Removed counsellors are not listed when assigning clients
     8.  Removed counsellors are not shown in full counsellor listings
     9.  Removed counsellors cannot log in as counsellors to the AB
         system.
    10.  It is not possible to send mail to a removed counsellor.

Note that a few extra requirements have come out here.  The previous
prose said nothing about whether removed/retired counsellors can receive
mail.

You'll also note that items 3 and 4 don't actually have anything to do
with removing a counsellor as there may be other reasons to
unassign/reassign clients other than removal, so this should be in a
separate section.

But most importantly you'll notice that each of these statements is now
testable.  You can either say "yes that is fulfilled" or "no, it isn't".


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

In the end I wrote an SRS (about half way through the project) and they
agreed to it, but didn't sign off on it.  I hope their verbal agreement
will be enough!


Okay, another story.  When I was working with a different group of
people.  We were asked to design and implement a newer, more extensible
system similar to something that already existed and was owned by the
client.  This system took video input from several cameras (preferrably
4) and output MIDI events.

We did all the documentation even though it was painful and even though
we knew nothing about the language we were to implement it in, receiving
video or generating MIDI events.  What we wanted out of the system was
fairly well defined, and since that's all the SRS is, that bit was easy.

You don't have to have an idea of how it'll work to write the
requirement.  If your requirements specification is getting down to
what shape the buttons appear and on what screen then you're drilling
too deep.  The requirements should be as concrete as you can make them
while allowing as much movement within them for the programmers as
possible.  They should be as specific as possible where it matters
however.

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!

I'm going to finish up here, as I've got to get back to that project for
AB so we can get the damn thing out of the way.  We're writing SRSes for
all projects now, no matter HOW busy we are.

All the best,

	Jacinta




> 
> Thanks...
> 
> --jc
> -- 
> Jimen Ching (WH6BRR)      jching at flex.com     wh6brr at uhm.ampr.org
> _______________________________________________
> Programming mailing list
> Programming at linuxchix.org
> http://mailman.linuxchix.org/mailman/listinfo/programming
> 

--
   ("`-''-/").___..--''"`-._          |  Jacinta Richardson         |
    `6_ 6  )   `-.  (     ).`-.__.`)  |  Perl Training Australia    |
    (_Y_.)'  ._   )  `._ `. ``-..-'   |      +613 9354 6001         |  
  _..`--'_..-_/  /--'_.' ,'           | contact at perltraining.com.au |
(il),-''  (li),'  ((!.-'              |   www.perltraining.com.au   |