XML Schema

Chapter 14. Documenting Schemas

The issue of documenting schemas—or any machine readable language—goes beyond simple additions of comments. The real challenge is to create schemas that are readable both directly by looking at their source code and by documentation extraction tools.

Style Matters

Writing schemas is much like writing programs. Two pieces of code may both work, but one is more readable and maintainable than the other. Readability is good.

Keep It Simple

Although W3C XML Schema has been carefully specified so that schema processors can find their way through the most complex and intricate combinations of its many features, the same can’t be expected of the average human reader. I must confess that I, for one, am getting rapidly lost in the meanders of medium complexity schemas, such as the famous schema for schema.

“Keep it simple” is a useful principle. Although W3C XML Schema gives you a huge number of features, you don’t need to use all of them in every schema. Each of them incurs a price in terms of readability of your schema.

Some of the rules for simplicity that we have used for some time with programming languages apply here, such as the conflicting rules for brevity (“If a function is more than one page long, split it”), and directness (“A function should be called more than once”). There are, of course, others such as “Put the code and the documentation in the same place,” “If you can’t say it in English, you can’t say it in C/C++ (or Java, C#, Perl, Python, ...