specs

[William Tanksley]

On Fri, 1 Jan 1999, RE01 Rice Brian T. EM2 wrote:

>> Bad definition of object.  Whatever they are should be defined by
>> their properties, not by their implementation details (bytes???).

>it's not the definition, it's merely a way of saying "what it is" in a
>paradigm like the C language's, to allow some implementation starting
>points.

To a certain extent that's helpful -- the problem is that by and large
your 'specs' posting contained almost nothing but theory, and pretty
abtruse theory at that.  Before we enter the implementation phase we need:

 - concept.  It should explain the problem and solution briefly, and
mention the constraints and major risks.  This is close to what you've
just posted, even if I can't understand most of it due to the theoretical
level (that isn't a bad thing for your document, although it will limit
the number of coders you can get). Your discussion lacks any mention of
risks, although that's perfectly understandable.  Less understandable is
the lack of acceptance criteria (Tunes suffers this same problem): how
will we know when our systemm will mmeet your expectations?
 - requirements.  This should be a dissection of the problem being solved 
by the system, with perhaps some hints of the general characteristics of
the solution (although in a perfectly formal world it wouldn't prejudge
the solution).  The Tunes web page might serve as an example here.
 - specification.  This should take the parts of the problem identified
in the Requirements document and describe the solution for them.  It
should also identify the general architectural ideas of the solution, and
some more detailed acceptance tests.  Public interfaces must be fully
defined here.
 - design.  Yeah, the usual -- just expand on the achitecture described in
the spec.  Good tools to use here are diagrams, data dictionaries, class
relationship charts, and such.  All modules and interfaces should be fully
defined by the end of this.
 - detailed design.  Write the pseudocode or the literate programming
code, and perhaps somme of the actual code (this always is a bit blurry,
except in the most formal projects).
 - coding and unit testing.
 - systems testing.
 - acceptance testing.

This is, of course, typical of the waterfall model, which IMO plans way
too far into the future (and is thus too inflexible).  My favorite
development model only plans one or two steps into the future, and
includes an assesment of risks at the beginning of each phase.  However, I
don't think that's any of my business right now.

[some very good problem statements removed]

>is merely syntactical orthogonalization of all meaning.  its therefore a
>completely general-purpose mechanism for isolating meaning and mechanism.  i

This is kinda hard to wade through, but this is a good example of one of
the problems caused by the lack of a Requirements document -- you didn't
have a definition of 'meaning', much less any relation of 'meaning' to the
problems we're wondering about.  My own native understading of the word
'meaning' doesn't (and shouldn't) help here.

My mom just saw your paragraph and started laughing.  She points out that
the part I've quoted should be written with the second sentance first,
since it implies to which concept "meaning" is supposed to be orthogonal.
(She's an English major, very little math education, but being a long-time
homeschooler she's picked up a lot of technical savvy.)

>what i'm saying about arrow-creation is that it will always be contained
>within some context, just as a message from the user to "delete all" should
>never nullify the system, because the system already is limiting the user to
>some context in order to ease interface problems.

Nice paragraph, good comparison, and a great job of bringing in past
solutions to illuminate the present one.

>> It's getting there, but still way to general yet.
>> And it is far from complete.
>ok.

I hope I've given some ideas of how to make it more complete.

Honestly, the more I study your work, the more I'm impressed by it -- but
it takes a LOT of study, and I didn't start out very impressed at ALL.

>> An simple example:
>> At work we are given descriptions of output files that need to be
>> created from our database.  We are told the record size.
>> The starting and ending position of each field.
>> The way data should be represented in each field.
>> A description of what data should be placed in each field.

>i'm not sure how this relates to this case.  could you explain in a more
>explicit way?

I'm afraid it doesn't.  He's accustomed to working in a formal environment
where the coders see the final result of the design.  We're not at that
point yet.

>> For your arrow language, we need.
>> A precise specification of exactly what is your arrow language.
>> A description of what each of the operators does, and some description
>>   as to why you picked what you did.
>> A description of how the arrow language can be used to make a complete
>>   system.
>> No implementation details except as hints.

>most of it is just syntax.  semantics would derive from the system of arrows
>made by the user itself.
>i will, though, walk through the ideas for operators in more definite terms
>and give examples in a little while.

I would find it helpful if you would step back and write a Requirements
document, and perhaps even some acceptance tests (possibly in the form of
use cases).

>> This should break tunes down into 2 hard problems (implementation, and
>> specification) instead of 1 monster, problem.

>yes.  i would like that too, as long as i can trust you all to implement it.

You can't.  But you can trust that the work will result in a stabler and
more useful conception of the problem and solution, which is more likely
to be understood by a capable coder or designer.

Good luck.

-Billy