"Clean Specs"

Mon Feb 8 15:55:00 GMT 1999

Message authorized by:
    : paul at prescod.net_at_INTERNET at X400PO
-------------- next part --------------
     Paul Prescod wrote:

     >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's face it,folks, people do their best work when they're allowed to do 
what 
they do best.  With this in mind, I would like to make a modest proposal to 
future standards writing committees:  (1) The job of the people actually 
writing
the standard is to concentrate on precision and elegant simplicity, even if 
this
means using the notation of mathematics or symbolic logic. (2) All standards 

writing committees must have one or more staff members who are technical 
writers.  The staff members' job is to be "intelligent laymen (lay persons?
)", 
to listen to the proceedings, ask questions to help with their own 
understanding, and to explain and interpret the standards in operational 
terms 
to the rest of us (3) All standards will be published as "annotated 
standards" 
with the annotations published in alternating blocks of text, perhaps in a 
different type font.

The object of this proposal is that it allows each group of persons to do 
what 
it does best and assures that there will be no lag time between the 
publication 
of the standard and the publication(s) of interpretations.    

______________________________ Forward Header 
__________________________________
Subject: "Clean Specs"
Author:  owner-xml-dev at ic.ac.uk_at_INTERNET at X400PO
Date:    2/7/99 10:42 AM

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)