"Clean Specs"

[Borden, Jonathan]

Paul raises some important points here.

The question is as to what is the best way to write specs, best being
efficient and clear.

The namespace spec is often used as an example of an unclear spec. I do not
agree with this. When I read the namespace spec it is very clear. My
misunderstandings of the spec have come almost entirely from *every thing
everyone else has been saying* about namespaces rather than the spec itself.
Being somewhat of a neophyte, I assumed that there existed concepts within
about namespaces that I missed from the very simple spec.

The simplicity of the namespace spec was driven home by the examples James
Clark has given.

To me this is an excellent example of why a spec should be written in 3
parts: a formal specification (BNF or whatever), a plain english
description, lots of good examples.

Here is my plain english distillation of namespaces: Namespaces are a way to
distinguish element and attribute names using URI's so that element and
attribute names can be reused without causing problems for software. <<
formal description here >> For example ...

Paul is correct that formalisms obfuscate specs for neophytes. The problem
is that english is ambiguous. For those of us who can't read formalisms nor
english a good set of examples are needed.

The best RFCs contain these three parts.

Jonathan Borden
http://jabr.ne.mediaone.net

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


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)