xml-dev - Re: Improved writing -- who's going to pay for it?

[Rick JELLIFFE <ricko@geotempo.com>]

Ronald Bourret wrote:
> 
> tpassin@home.com wrote:
> >
> > Yes, I know, but better writing/editing makes the result stronger and
> > (potentially, at least) more useful to those same companies.
> 
> I'd remove the "potentially". The result is always more useful.
> 
> The schema spec is a good example. Once I finally waded through it, I
> found I liked most of what it offerred. Contrast that with the fact that
> even now, whenever I pick it up, I get really p----d off at the fact I
> can't understand anything it says. I can't help but wonder how much of
> the controversy over schemas was due simply to frustration.
 
All spec-writers face the same kind of problem.  If one uses algebras
then no-one can understand it.  If one uses simple formalisms then you
end up having to add so many exceptions in text that the simple
formalism is misleading.  If you define a technical vocabulary and use
simplified English, then people insist on reading it as if it were
natural English and with the words meaning whatever they mean in the 
domains that the reader is familiar with.  If you use natural English,
then it is too fuzzy to communicate, and the idioms and vocabularies of
one nation are not shared by others (for example, someone complained
that the XML Schema spec used "elide" and "obtain" in ways that seem
perfectly usual to me.)

The prime readers of XML Schemas specification is implementers of XML
Schema processors; a secondary audience is developers of XML Schemas
(hence the Primer). Intelligability in one sitting is simply not a major
goal, though it would be lovely. After anything gets to a certain level
of complexity, a linear exposition is not possible and so a symphonic
exposition is required: it is a perhaps version of the writers' classic
dilema of how to handle recursive definitions (e.g. how to introduce
entity references in an exposition on XML data content before you have
introduced markup declarations). There are a dozen ways to organize the
Schema specs for clearer exposition for users, and I hope authors will
soon be busy on finding them out.  

The most telling issue is this: people who have written specs very
rarely complain about the prose of other specs.  Instead, they often
have great sympathy for the view that you should either limit the
technology to ways that can simply explained (i.e. sacrifice power for
expositional simplicity, but then people will complain about lack of
bangs per buck) or you should pick the most elegant algabra for
explaining it even if then you need to spend a lot of effor explaining
what it means (i.e. the e=mc^2 effect).  

I am not saying "put up or shut up"; but there is something practical
you can do: when you find a paragraph that is bad, draft an improvement
and send it to the xml schema comments mailing list.  It won't make it
in time for the CR draft now, but I am sure the editors will be
delighted to have suggestions. The editors are not trying to create
incomprehensible specs: to the contrary they are trying very hard to
integrate the progressive refinements of XML Schemas by the XML Schema
Working Group.

Cheers
Rick Jelliffe