How to document an XML Schema?

Question

I have developed a XML schema for an application I wrote. Now I want to document the valid structure for the end user, however I can't come up with any natural way to do this. I've seen things like xs3p, which essentially converts a xsd schema to a HTML representation, however that doesn't look like good documentation to me; the user shouldn't need to know anything about schemas to understand what he is allowed to do.

Any ideas how to document this? Any programs / editors / graphical solutions or simply concepts I can build on?

Answer 1

The best way (after 6 years of experience with xsd and designing/coding system to system interfaces) in my opinion is to use the xsd:documentation and xsd:annotation that are designed for this. This way the XSD is self documenting (much like the java doc you have in the source code) and the documentation is always distributed with the XSD. Look at the example from here and how the documentation is shown in-place in an XML editor.

If you doesn't want to do this then I suggest you look at this post How to convert xsd to human readable documentation?