"Clean Specs"

[Paul Prescod]

What is a "clean spec?"

People in this discussion are mixing together a variety of things that I
do not consider the same.

Uche Ogbuji wrote:
> I have worked on teams implementing DOM, XSL and parts of XLL.  Some users
> might grant that we have been "succeeding", but let me assure you that if so,
> it is despite the W3C specs, not because of them.  DOM, especially is
> unforgivably inconsistent, incomplete, and unclear for a production-ready
> (1.0) specification.

There is not a SINGLE person on this mailing list that would say that it
is right to create specifcations that are inconsistent, incomplete or
unclear. It is beyond doubt that specifications in the XML family,
including XML itself, have these problems. The question is how to avoid
that?

 * some people say that what the spec needs is "more English". But much of
the problem with the namespaces specification comes from ambiguity in the
English.

 * some people say that we need "more non-normative text" but once again,
it is a non-normative appendix that is confusing people.

What almost nobody has suggested is that we need more formal notation. Now
if we look at James Clark's "clarifying" document what we see is *less*
English text and *more* notation.

As David Megginson has pointed out, when a spec. invents a notation to
explain its abstract concepts the spec. becomes temporarily harder to read
because you have to learn the notation before the specification. This will
turn people off. I remember that Algebraic notation turned me off in my
first year math classes. But in the *long run* it makes life easier for
everyone. Implementors have precise definitions of what the hell they are
supposed to implement. End-users get software they can use. People reading
the specification for their own education and edification will understand
it better -- if they perservere through the task of learning the notation.

I know that W3C spec. writers are under pressure to use more normative
English and less normative notation. This is not a vote for "clean"
specifications. It is a vote for messy, hard-to-implement ones. Where is
Dan Connolly when you need him?

Let me point out: the CSS and HTML specifications are easy to read because
everyone who wants to read them already understands the basic concepts of
web pages and layout. They are concrete implementations of ideas we
already understand. The same goes for Java. (and yes, I read the Java
specification, but AFTER I already knew Java)

I wonder if anyone on this list has ever learned a language that was
radically different from what they already knew through the language
specification: Scheme, Prolog, APL?

Technical writing is damn hard. When you do it right, you must make
certain decisions about ordering of concepts and revelations that are the
exact opposite of what you do in writing a specification. When you write a
spec., you need to present things in the order of fundamental building
blocks to high level concepts. In technical writing you will put your
students to sleep if you zoom in on details before explaining the general
framework. 

I've told people who want to read the DSSSL specification to start at the
back and work forwards. Of course once they become implementors then they
read it the opposite way around. Life is hard for implementors. I'd rather
be forced to implement the entire suite of XML specifcations over HTML/CSS
2. That isn't a slight against HTML/CSS, it's just an attempt to put
things in perspective.

 Paul Prescod  - ISOGEN Consulting Engineer speaking for only himself
 http://itrc.uwaterloo.ca/~papresco

"Remember, Ginger Rogers did everything that Fred Astaire did,
but she did it backwards and in high heels."
                                               --Faith Whittlesey

xml-dev: A list for W3C XML Developers. To post, mailto:xml-dev at ic.ac.uk
Archived as: http://www.lists.ic.ac.uk/hypermail/xml-dev/ and on CD-ROM/ISBN 981-02-3594-1
To (un)subscribe, mailto:majordomo at ic.ac.uk the following message;
(un)subscribe xml-dev
To subscribe to the digests, mailto:majordomo at ic.ac.uk the following message;
subscribe xml-dev-digest
List coordinator, Henry Rzepa (mailto:rzepa at ic.ac.uk)