Re: Generating documentation for XML schema files

[Mark Giffin <mgiffin -at- earthlink -dot- net>]

Hi Cheryl,

I have seen the documentation output from XMLSpy, and it is similar to 
the output from the Oxygen XML editor:

http://www.oxygenxml.com/

I usually find that the output from these tools is overly complicated 
and even bewildering, but both of them look good, with lots of little 
graphics and diagrams and show/hide features (in the HTML output). 
Probably the problem is that the vendors have no idea what you are using 
the docs for, and who the audience is. So they try  to cover the bases. 
But with Oxygen and I'm sure with XMLSpy, you are provided with many 
configuration options and output formats for the docs and maybe you can 
come up with a reasonable result. I have not played with these options. 
I'm sure you could customize the output in many ways. For one example, 
Oxygen has a DocBook XML output, and you could write an XSLT script to 
adjust the DocBook to your liking. Or you could customize the HTML 
output, etc.

I don't know much about the other two tools you mention, but I will 
assume they work in similar ways. They analyze the XML schema and 
present the structure of it in various ways. There will be no 
documentation other than that unless you add <xsd:annotation> elements 
(and related elements) to the schema with descriptions of the various 
pieces. Possibly some of the tools let you merge in descriptions that 
are external to the schema.

I have not used any of these tools for actual doc work. I have always 
opted for writing XSLT scripts that run through the schema and pull out 
only the bits I want. It's usually pretty quick but I already know XSLT.

Mark Giffin
http://www.markgiffin.com/

On 1/20/2012 9:16 AM, Cheryl Magadieu wrote: