Editorial suggestions for XSD 1.1

I mentioned a while back that I would have a look at the text in XSD 1.1 and 
see if I could make any suggestions that would make it easier for a 
developer to read.  I think this is important because the easier the spec is 
to understand, the more people will use it and the more revenue companies 
like mine will make!  I've concentrated on minor tweaks rather than a full 
re-write as some have suggested.

For this exercise I tackled the section on complex types as I believe this 
is the most unwieldy.  Here are the main conclusions I came up with:

- I've used notation along the lines of {base type definition}.{content 
type}.{variety} to replace the more narrative way of describing properties 
within properties.  Such notation would need to be described in the earlier 
sections (2.x.x) of the document.  I think this makes the text much easier 
to read.  Fewer brain cycles are spent on working out what is being referred 
to, and more can be spent on working out the bigger picture.

- For multiple nested clauses of 'one of these' and 'all of these' I've 
prepended the various sentences with 'Or' or 'And' to help the reader 
remember what is going on.

- Some sections repeatedly use the phrase "type definition .resolved. to by 
the .actual value. of the base [attribute]".  It's easier for the reader 
just to use the term "{base type definition}".

- Some sections say things like, "If X and Y and Z and you're using 
<restriction> then".  It's easier for the reader to have the context first, 
eg. phrase as "If you're using <restriction> and X and Y and Z then."

- I've found that defining a few additional terms makes describing some 
sections easier.

- In some cases a little bit of up front text about why a set of rules is 
being applied helps set the brain for what is to follow!

- "Not absent" feels a bit like not not there, i.e. a double negative.  The 
addition of a feel additional terms, which can be defined in terms of those 
terms already defined, e.g. present = not absent, would help the clarity.

- Avoid as many "it" and "it's" as possible.  Sometimes it takes a while to 
work out what it applies to.

I haven't broken the section into multiple parts as I had hoped, as I can 
see that the various parts are very intertwined.

The results of all this (and a few other bits) are illustrated in the 
following version of the complex types section:

http://www.tech-know-ware.com/lmx/download/Editorial-suggestions-for-XSD1.1.pdf

I hope it is of some help,

Pete.
--
=============================================
Pete Cordell
Tech-Know-Ware Ltd
for XML Schema to C++ data binding visit
 http://www.tech-know-ware.com/lmx/
 http://www.codalogic.com/lmx/
=============================================

Received on Tuesday, 24 April 2007 11:41:56 UTC