A prelimary specification for design specifications

[Eric W. Biederman]

Comments, critiques, and especailly specs written for tunes on these
guidelines would be appreciated.

After it is decided to adopt this draft specification how should does
it get put on the tunes web pages where everyone case see it?

-------- specs.txt ----
A specification for program design specifications.

-- Design requirments
Specify clearly what a good design is so that the tunes project
may have use a seperation of labor, into design and implemenation, 
so that the tunes project may move forward.

-- Definition of a design specification:

A specification is the detailing without unintentional ambiguity of
what a system should be, to a specified level of detail.  It should
contain reasons for design choices.  It should satisfy all of the
design requirements.

The format of a specification is important.  The specification should
be a single work, and it should be designed to be used a reference
work.  Further an attempt should be made to keep specifications in
a single organization to the same format.

Specifications should be maintained as something which may change,
and no specification should be considered final until at least one
complete prototype implementation exists.

-- Level of detail

This specification will not attempt to set coding, or formatting
standards for specifications.  Nor will it attempt to bring to light
the design specifications of tunes.

This specifications purpose is to bring to light, the issues needed
for writing a good specification, suggesting implementation issues
at the same time would endanger this specification from being adopted.

Taking everything a small solid step at a time seems best to me.

-- Reasons for various parts of this specification:

1) Listing of design requirements
Listing these allows testing to see if your design is complete.
As well as providing a focus while the design is being written.

2) No unintentional unambiguity.

First the level of detail that a specification is written to 
defines a level past which everything is ambiguous, as that is the
implementors job.  But this is a clearly set line of ambigiuty.

Allowing no other ambiguities without reasons being given allows,
checking of the specification to see if there are areas it is
incomplete.

This actually a mechanism I'm not quite certain about.  It was
intially added to the definition to help with problems, that
specifying a level of detail you are designing to solves.  

I think it still does more good than harm even it appears unnecessary
to me at this time.

3) Reasons for design choices

It allows other designers to critique your design.

It allows implementors to be responsible for some of the design
invariants.  Ensuring that reasons that are given meet all of their
designed purposes is an example from this document.

It allows personal review of design choices, clarifying your vision,
and suggesting changes you should make elsewhere in the specification.

4) Specified level of detail

The purpose of the specification is to allow seperation of different
sets of challenges.  In particular the challenge of designing a system
that meets specified goals versus the challenge of implementing that
system.

Selecting a level of detail for the implmentation division of labor
should be done on those grounds.

Suggestions from either group may cross that line but are to be
treated as just that suggestions.

5) Single Work

A single work allows implementors to easily find the complete
specification.  

A single work concentrates development attention on that work,
and there is a sense of progress as that work evolves into what
it is supposed to be.

6) Reference Work

Implementors will refer back to specifications frequently, while
creating their implementation.  The better a work is at presenting
it's ideas clearly, and making them easily found the easier it is for
the implementor to comprehend the work.

And with better comprehension comes a better implentation, as well as
an implementation that meets it's requirements.

Further with early comprehension of a well setup written/designed
specification, problem issues are likely to be appearent earlier in
the implementation, rather than appear towards the end of it.


7) Same format.

This allows any investment a person makes to be able to read and
comprehend one specification reusable on the next specification.

Further this allows all of the authors of specifications to
standardize on the same tools, and share improvements in the tools
they use for writing specifications.

8) Not final until implemented.

Until someone has actually implemented something fully there could be
hidden technical issues that don't appear until a complete
implementation is done.   If these technical issues make a system
impractical the design must be changed.  

If these kinds of issues come up garanteeing compatibility with these
specifications could be a nightmare.

9) allowing change.

Specifications are likely to change.
Either because the requirements of the specification change, or
because of issue that are not forseen until the actual implementation.
Or because simply people make mistakes.


-- Areas for further consideration
Examine RFC's and X consortium standards and see if they
their methods do anything I forgot.  

Hopefully however we won't need to get too legalistic about this.
In which case what I have provided should be enough to get tunes into
a specification writing phase.