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

[Ronald Bourret <rpbourret@rpbourret.com>]

Rick JELLIFFE wrote:
> 
> The prime readers of XML Schemas specification is implementers of XML
> Schema processors; a secondary audience is developers of XML Schemas
> (hence the Primer).

I both agree and disagree with this statement. On the agreement side,
implementers are the ones who actually enforce the spec, so it is
vitally important that they understand it. (They also win by virtue of
being in the minority -- if more people wrote implementations than
schemas, the spec would probably target the authors, not the
implementers.)

On the disagreement side, I'm not sure I like the implication that
schema authors aren't important. While I don't mean to say that you
meant this (I can't imagine that you did), I have an uneasy feeling that
this sort of attitude is exists in the spec writing community -- sort of
a macho "if you can't understand it you don't deserve to" thing. And
while I do agree that specs will never be accessible to all readers, I
think the line should be drawn further out than it currently seems to
be.

> The most telling issue is this: people who have written specs very
> rarely complain about the prose of other specs.

I guess I'm one of the rare ones, then :)

> 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.
>
> [snip]
>
> 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.

Guilty as charged.

However, I'm not sure that fixing a paragraph or two will have any
effect in this case. The problem is one of tone in the entire spec: in
my opinion, it simply leans too far towards terseness and should be
rewritten from the ground up.

While the WG has undoubtedly considered this, the fact is that, in spite
of a long history of complaints, they have decided for the moment to
leave things as they are. To me, this means that a majority of them
feels that comprehensibility is not a critical enough issue to warrant
the time and resource hit a rewrite would require.

My point is that comprehensibility is critical, and that the lack of it
is affecting things that are critical to them, such as reader input,
implementation experience, and rapid acceptance.

-- Ron

-- 
Ronald Bourret
Programming, Writing, and Training
XML, Databases, and Schemas
http://www.rpbourret.com