[TriLUG] how to document an XML schema across versions

[Hrivnak, Michael]

I have a documentation project to tackle, and I think the key will be
having the right tool. I'm hoping one of you can point me at something
appropriate.

Background:
There is an XML schema that's been in wide use for a long time with little
documentation. It has changed over the years as the tools that read and
write it have changed, but nobody has taken the time to carefully document
those changes. Those tools have been strongly versioned, so it's best to
think of the XML schema as being versioned in-step with the tools. A wide
range of these tools are in regular use today.

Other third-part tools sometimes need to consume this XML, and the lack of
docs makes integration painful. Periodically we discover yet another
"gotcha", where some particular version had something unexpected; I want
somewhere to document that.

Goal:
I want to document the schema, and especially how it has changed over time.
I need it to be easy to see that an attribute didn't exist before version
x.y.z, had a default value of empty string starting with some other
version, then went to a default value of "0" in a later version.

Human-readability is the most important goal. Being able to validate XML
with the documented schema would be a bonus.

Have a suggestion for how to represent this? I could produce something
valuable with a word processor by using comments all over the place, but
that seems like it would get out of hand and be cumbersome to use. It
wouldn't show me "here's everything that changed from version x.y.0 to
x.y+1.0.

Thanks,
Michael