Best way to document XML

Question

Lately I've been dealing with Magento (a PHP eshop framework) which makes extensive use of XML files to determine how it should behave. Seeing as documentation isn't Magento's strong suit, I've come to a point where it would help a lot if I started keeping a record of the possible configurations of these XML files; what element can go where, why, what it means, what its value should look like, etc.

As a result I've been looking for the best way to create this documentation in such a way as to make it trivial to look up information as I'm creating the XML file. Of course this started with Magento, but it applies to XML in general.

So far I've used PersonalBrain which, I have to say, lends itself well to this kind of thing. I was wondering, however, if there is a better/preferred way of doing this. Ideally it should be free and have the ability to share this information later on in some widely-used format (for example HTML).

Answer 1

I would say the best way to document XML is to have a corresponding schema file for the document. This schema will impose what can go where and what the data should look like and you can also add additional comments alongside the elements in the schema.

Answer 2

As said by KevB, writing an XML schema (XSD) is probably the best way to go. In addition to what he said, there are automated document generators that can take your XSD and generate documentation for you (e.g. HTML/output), which will incorporate the comments written in your XSDs.

Answer 3

I'm not familiar with Magento, but if it's using XML files for its configuration then I'd be surprised if it doesn't already validate those files against its own XSDs. In that case you should be able to grab those XSDs and annotate them for your own use.

Answer 4

Don't forget about the annotation tag for your schema. It's more useful than comments because annotation tags are mostly ignored except you can use an XSL to strip them out and find the code to which they refer in one go. Kinda like Doxygen.