RE: XPATH differences between 1.0 and 2.0

 

Basically I don't agree that a spec should only be readable by the people
who wrote it. 
 
Well, nor do I! I wouldn't suggest that for a minute. And I think most of
the editors of the specs in this publication set have done an excellent job
of writing text that is highly readable "by technologists". The fact that
there are a good number of implementations developed by people unconnected
with the Working Group is good evidence of this. But the editors have worked
within the constraint that they are writing a spec and not a tutorial. That
means they don't have the luxury of saying things several times in different
ways, of describing analogies with other languages that the reader might be
familiar with, of glossing over some of the complications that most users
won't be interested in, or of explaining why the language is designed the
way it is.
 
It's not a question of whether the specs should be readable, it's a question
of who the target audience is, and what information the target audience is
expected to be seeking. And, for better or worse, we decided that we didn't
have the resources or process as a committee to write for the "clueless
reader". We felt there would be plenty of other ways that people would be
able to get that kind of material (which might perhaps not be the case for
more specialist languages such as RDF and OWL).
 
I would recommend that when reading specs, you do so a lot more slowly and
carefully than when reading a book. My own approach is to read the whole
thing once through from start to finish, to get a feel for the structure and
for what kinds of information can be found in different parts. Then read it
again more carefully, reading each paragraph two or three times until its
meaning is clear, and following any cross-references to definitions of
technical terms.
 
I have to say that I am full of admiration for people who read material like
this in a language that is not their own. I know that when I read technical
papers in French or German it is ten times more difficult than reading them
in my own language. This is another problem that the WG is not well placed
to address itself, but where we hope that the market will fill the gap.
 
Michael Kay
 
  
A well-structured and well-written spec should allow anyone to read it. If a
spec is not readable even by technologists, it will be counter-productive
for the technology itself because it could not be endorsed. 

The W3C is full of Primer success documents, such as RDF, OWL, and so on. I
think there is a place for W3C tutorials and for book detailed tutorials
with plenty of use cases.

Best Regards

Michael Kay escribió: 

My comment about the XPATH 2.0 TR is that it is not easy to 

see at first glance what are the differences between 1.0 and 

2.0 versions. Also I'm missing an "XPATH Primer" for the 

clueless reader.



    



A personal response:



Concerning differences between 1.0, it would have been nice to provide this

information but it would have been a very long list, and it would have been

difficult to ensure its accuracy. We felt it more important to concentrate

on areas of incompatibility, which are covered in Appendix I.



Regarding a primer, we took the conscious decision that it was best to leave

provision of tutorial material to the market. This makes particular sense

for version 2.0 of a specification. The W3C process is not a good way to

write and publish tutorial material, because it has to be discussed in

committee and voted on. You can get books on XPath 2.0 (for example, my own

from Wiley) which attempt to meet this need. A book author can say helpful

things that a W3C working group can't say, for example "this feature is

implementation-defined, but as far as I know everyone except Microsoft does

X".



In my XPath 2.0 book, each section describing an XPath 2.0 feature has a

subsection "Changes from XPath 1.0" which explains what's new.



Generally, W3C specifications (like those from most standards bodies) are

not designed to be read by clueless readers. Their purpose is precise

specification of a language, and this can often make them difficult to read.



Michael Kay

http://www.saxonica.com/