Tool for documenting XML format?

views:

answers:

+2 Q:

Tool for documenting XML format?

Hello,

Can anybody suggest a good tool to document the format of an XML document? I'm not looking for DTD or something that validates XML; I'm looking for something that helps me generate documentation that describes in plain language what each node/attribute/value is for.

+1 A:

DTDs and XML Schema languages are the preferred method of documenting XML. I would say research XML Schema or RELAX NG and then write a XLS-FO or XSLT transform to convert the XML Schema to DocBook. From there you can generated HTML, PDF, Word, whatever format you want. There are already scripts that will do this for you with some patient Googling I found xsd2db. The great thing about DocBook is the variety of output formats is very rich and it is easy to create your own if you don't like any of the numerous output formats available.

The bonus is that you now have documentation and validation in the same file, so you don't get drifting artifacts that don't match the code anymore. You can automate all this chaining as part of your build process.

fuzzy lollipop 2010-10-22 14:09:09

That all seems like a lot of work just to generate a document that says stuff like "node X tells the program how to do Y. It has sub-nodes A, B, and C, and property D" (in a prettier, more organized format, of course). I'm looking for something between what you described and having to spend the afternoon formatting text in Word.

Kelsey Rider 2010-10-22 14:46:02

XML Data structures used as data transfer mechanisms in real world systems are living things, they change, that is guaranteed. The best long term solution is to automate a tool chain like I suggested. You do the work once, then all you have to do is add XSD files to a directory and process them with a shell script using that xsd2db. Less work than doing it once in Word. Someone already did the work of specing out the XML Schema standard, not reusing it and rolling your own documentation would be a travesty in wasted time. Much like not using JavaDoc in a Java system.

fuzzy lollipop 2010-10-22 15:45:43

The JavaDoc tool chain is a good analog, would you rather document it the classes and methods in an excel spreadsheet and have to manually update that thing every time some detail changes. That wouldn't last long and the effort in the documentation would be wasted, and worse now you have incorrect documentation, which is almost worst than none.

fuzzy lollipop 2010-10-22 15:48:16

Are you looking for rdf?

EDIT:

If you are not defining the XML and it is already there, you need to generate the documentation, please discard this. But if you are describing it now, I think rdf would be best, because it allows you to describe the xml in terms of resource and a resource can be data or method or etc.. which allows you to describe "node X tells the program how to do Y". And thats why hypermedia.

yadab 2010-10-22 14:14:48

How exactly would RDF help documenting an XML format in plain language?

stakx 2010-10-22 19:06:44

@stakx : The answer is for the requirements that he is asking for? With plain xml it is not possible (use whatever tools you want). So, please read the section EDIT.

yadab 2010-10-23 01:16:02

@yadab, while this probably won't answer the OP's question (as RDF is likely more intended for machine processing than for humans), it still sounds intriguing. Could you perhaps add a small example to your answer, esp. how you would say "node X tells the program how to do Y" in RDF? This sounds very difficult to formalise. (Note btw. that I didn't vote you down.)

stakx 2010-10-23 06:34:52

I'd recommend writing an annotated XML Schema and processing it with xnsdoc or a similar tool. Writing the schema can be tiresome, but it provides an understanding of the structures that you won't be able to convey using example data only. And while xnsdoc does have its quirks, it generates usable output with rather little effort.

vwegert 2010-10-22 19:01:12

What you need is a XML comment extractor and documentation builder. ( I couldn't find any on the Web, it could be a nice little project if anybody is interested). Just like source files are documented using comments which can then be extracted by a tool to generate API documentation, you will need a tool which would treat XML as source and extracts the comments to create documentation.

Suresh Kumar 2010-10-24 04:01:52

ansaurus

tags:

views:

answers:

Tool for documenting XML format?

related questions