Clearer W3C Specs (was Re: XML Information Set is seeding impenetrable language; reconsider?)

[Thomas B. Passin]

Michael Champion wrote:
>
<snip/>
> The need for better writing in W3C specs was discussed at a recent W3C WG
> meeting I attended.  That particular group generally agreed that the specs
> need to be written more clearly, and the plan (I don't know if anything
came
> of it) was to lobby our W3C Advisory Committee representatives to push the
> W3C to devote more of its admittedly scarce resources to hiring staff
> technical writers, or getting members to contribute the time of technical
> writers as well as XML specialists to the activities of the working groups
> they participate on.
>
> This posting (and a diatribe against the Schema draft that I saw today)
> reminded me to bring this issue to my AC Rep's attention. Can anyone
suggest
> other concrete proposals for improving the situation?
>
The thing about the writing is this:  the Recs must communicate clearly and,
we hope :-), unambiguously to would-be users.  Think of all the arguments on
this list that occur because neither the letter nor the intent of a Rec is
clear.  There are two common ways to improve on written material.  One is
peer review.  You should choose some reviewers that are expert in the field.
The second is mass review, sort of like beta testing.  Discussion groups
could do this.

Trouble with peer review is, who could you get, especially without pay, who
isn't already involved?  Trouble with discussion groups is, a lot of the
people responding are either not knowledgeable enough or don't read the
material closely enough. Still, where there is widespread misunderstanding,
the material probably needs rewriting.  This mechanism is already being
used, although I don't know how much it matters to the working groups.

The IETF won't bless an RFC until there are two independent implementations.
I think this is the right kind of approach.  Surely, Tim B's Lark
implementation must have been a great help to the XML committee (I'm
guessing, I don't really know anything about its role).  There's nothing
like trying to build to a spec to uncover its lack of clarity.

To some extent, these can all be regarded as issues of Quality Assurance.
It would probably be useful for the W3C to have written standards on the
required QA and how to apply them.  Maybe it already does.

Would anyone on one of the Working Groups like to fill us in on these
things?

Tom Passin


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/ or CD-ROM/ISBN 981-02-3594-1
Unsubscribe by posting to majordom at ic.ac.uk the message
unsubscribe xml-dev  (or)
unsubscribe xml-dev your-subscribed-email at your-subscribed-address

Please note: New list subscriptions now closed in preparation for transfer to OASIS.