"Clean Specs"

Sun Feb 7 16:58:19 GMT 1999

At 09:19 AM 2/7/99 -0600, Paul Prescod wrote:
>What is a "clean spec?"

Good question, one with many answers.

>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?

Glad to hear that we're actually arguing toward a common purpose.

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

What we need is text that conforms to the formal notation, and lots of
examples that are checked hard against both the text and the formalisms for
accuracy.  This is extraordinarily difficult to do right, but it results in
standards that are both solid and understandable.  

To a considerable extent this demands that spec writers see themselves as
implementors - and probably that they include implementors in the process,
especially implementors who don't have prior experience in whatever
standards provided the foundation of the current project.  The story for
XML 1.0 of using Peter Murray-Rust as a canary is a good one, though I'd
like to see more of that in the actual group of people writing the specs,
not just the surrounding groups.

One other point: putting explanatory text and examples into 'non-normative'
sections is pretty much equivalent to abandoning them, announcing that the
writers didn't put the effort to ensure that they were completely
conformant with the formal specification and therefore equally normative.
Making the _entire_ spec normative, both the formalisms and the explanatory
text, seems like a more likely approach to succeed, though again it
requires (considerable) additional effort on the part of the specification
writers.

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

Are there good resources describing formal notations?  I tend to find that
the people creating formal notations do so because they're fed up with
text, and then do a lousy job describing the notations.  All they've done
is make the learning curve a hell of a lot steeper, while creating a
subculture of experts fluent in that notation who then feel empowered to
use that notation to create all kinds of wonderful things that the rest of
us can't figure out.

I would _never_ write an XML book that started by explaining EBNF and then
used that to walk through the spec; I wouldn't expect readers to stick
beyond the first few paragraphs.  (It has been done before, and there are
readers who enjoy that, but in my limited experience they're a very small
minority.)

>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?

It requires making the effort to align the text and the formalisms.  Now
that we have XML as a foundation, that task may become simpler; I don't
find it very difficult to describe the structures of XML documents and XML
DTDs in plain English, even to those without extensive XML experience.
Making XML a common formal foundation is a good way out of this mess for
lots of standards - though that, of course, requires undertaking the
project Paul has described above of making the foundation formalism
intelligible.  

XML won't work as a common foundation for everything, so we'll still be
stuck with the other vocabularies for a lot of projects.  Spec writers will
still have an obligation to write clear text.

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

CSS was actually a huge jump for a lot of people in the HTML world; I'd say
it was harder than you make it out to be.  CSS2 is easy to read because it
recognizes that difficulty (more than CSS1 did) and addresses it directly.

I've never found the HTML specs to be of much use, though the latest drafts
look much more promising.

>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?

Never tried radically different.  I found the ECMA-262 spec for
ECMAScript/JavaScript much more useful for syntax than the books I was
attempting to use at the time, though that too required some effort.

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

It's definitely difficult.  I've spent about 100 hours this week
documenting assorted XML material to finish a book, and I've seen specs
with varying degrees of clarity, from super-sharp to non-existent.  (I've
also been dealing with numerous cases where text and formalism don't match
at all.  That's especially fun.)

I'm not convinced that technical writing needs to run backward from the way
that a specification must be written, however.  Starting out with building
blocks and constructing grander concepts is perhaps a nice theoretical
model, but I don't think I've seen too many specs that follow that
construct precisely.  Typically, specs at least present the big picture to
give readers some idea of why they're bothering, then focus in on details,
and then zoom back out.  Abstracts and introductions are at least as
important to writing a good spec as they are to writing a book, as are
glossaries.

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

Actually, once they get through the HTML-in-XML stuff, I think implementing
HTML/CSS2 would be a heck of a lot easier than implementing
XML/XLink/XPointer/XSL/fragments/XQL/etc.  That's your choice, of course.

Simon St.Laurent
XML: A Primer / Building XML Applications (March)
Sharing Bandwidth / Cookies
http://www.simonstl.com

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)