[TriLUG] how to document an XML schema across versions

[Peter Neilson]

As I tend to favor emacs, and because emacs seems to have an XML mode, I  
would use emacs to write tools and constructs for maintaining the schema  
with internal documentation. Emacs can apparently validate XML  
automatically, so there would be little danger of messing things up. Emacs  
seems to know that <!-- --> is an XML comment.

I've not used emacs on XML, but a brief peek at the documentation for its  
XML support suggests it might be worth an attempt.

On Thu, 12 Feb 2015 17:28:14 -0500, Hrivnak, Michael  
<mhrivnak at hrivnak.org> wrote:

> 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