xml-dev - Re: Standards and their users

[tpassin@home.com]

Miloslav Nic wrote about standards -

> Recently I have received quite a few mails complaining about standard
> understanding and have
> seen quite a few more on different mailing lists.
>
> I recommend these two to your attention:
>
> http://lists.zvon.org/l/showmsg.xp?ln=zvon&mid=18
> http://lists.zvon.org/l/showmsg.xp?ln=zvon&mid=7
>
> I am afraid that the gap between standards creators and their user
> community is widening with startling pace. From the time I have started
> Zvon I have spent hundreds of hours studying standards and in my
> personal experience it gets more and more difficult to read the next
> one.
>

I completely agree that the current standards are difficult to read and
understand, and would them to be more intelligible.  There are actually two
separate aspects to this:

1) Whether to illustrate requirements with examples or not.  There are
different approaches to this.  Some think that examples must be forbidden,
some that they should be liberally used.

2) The writing quality - clarity vs. formality.  Sometimes formality is
confused with comlexity, and simplicity in the text with lack of clarity.

Why would examples be forbidden?  Mainly because the text should stand on
its own (i.e., be "normative" - a terrible word, I think!).  Also, examples
might be inconsistent with the text, and then which should be followed?

Why should examples be allowed?  Because no text can stand completely on its
own, especially if the readers don't understand all the private concepts and
expressions that could not be completely spelled out.  Look at the legal
profession.  Nothing else is as precise and complex as a legal document or
law, but court decisions are still required to interpret the intended
meaning.

The W3C recs are all over the place in terms of these two aspects.  I mean
no disrespect to the editors, who (I am very sure) work very hard and
probably have an impossible job.  The language in any one document ranges
from extremely concise and precise to sentences that seem to have been added
because someone thought they read well.  Diagrams, when they are used, are
sometimes not as helpful as they could be.

Generally, I would say that the language - especially sentence structure -
is much too complex.  It would be better to pay more attention to what needs
to be conveyed to the rader, and to split up the language into simpler parts
with this in mind.

However ...
If you look at other specs, not necessarily software-related ones, it's the
same thing.  Try reading up on ASTM tensile testing methods, or the
requirements for nuclear-reactor-qualified stainless steel pipes, or
standard threaded bolts.  You have to learn how to read them - it is an art
that takes experience.  Writing them is even harder.  One gets to really
appreciate a concise and precise statement of a requirement.

Standards are a form of infrastructure. They need to be understandable by
those who build the tools and systems - parsers, protocols, and so forth.
Those builders must be able to go back to the standards, in case of
questions, and verify what is meant.  Others skilled in the art should be
able to reach the same conclusions, or at least they should all be able to
reach a "gentlemen's agreement" about how to interpret the language.  This
is how it works in C and Java, after all.  Tried reading up on the standard
C library?  Ha!

This should be the test for a standard.  Judging from the type of questions
that get raised here, the XML recs are marginal in this regard.  Still, the
parser, xslt processor, and schema engine people seem to be able to build
their processors, so the Recs must be more or less adequate.

What about the rest of us?  That's where good texts and products that come
with lots of useful examples come in.  Michael Kay's xslt book is a really
good example.  Personally, I like the approach of including a tutorial with
the rec, as the xsl-schema rec has tried to do with the part 0:Primer.

Too bad these books and tutorials can't exist at the beginning.  But then,
it's too bad most programmers don't comment their code adequately, too.  The
reasons are probably similar.

So let's encourage - even demand - the standard writers to improve their
writing (this means to be specific when we give comments and make requests
during development), and let's applaud people like Michael Kay and Miloslav
Nic who work hard to give the rest of us material we can work with.

Whew-that-was-long-windedly-yours,

Tom Passin