Re: Generating documentation for XML schema files

Subject: Re: Generating documentation for XML schema files
From: Mark Giffin <mgiffin -at- earthlink -dot- net>
To: Cheryl Magadieu <cmagadieu -at- gmail -dot- com>
Date: Fri, 20 Jan 2012 10:15:44 -0800

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:

One of the developers here plans to generate documentation for XML schema
files about APIs defined in XSDs. He's looking for suggestions for tools
that generate XML schema documentation. Some of the ideas that have been
tossed around are the XML Schema Documenter from CodePlex (
http://xsddoc.codeplex.com/), DocFlex/XML XSDDoc (
http://www.filigris.com/products/docflex_xml/xsddoc/), and XMLSpy (
http://www.altova.com/xmlspy/xml-schema-editor.html). Do you have any
experience using these tools--or any other ones--to generate XML schema
documentation? If so, which tool would you recommend?

Cheryl
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create and publish documentation through multiple channels with Doc-To-Help.
Choose your authoring formats and get any output you may need. Try
Doc-To-Help, now with MS SharePoint integration, free for 30-days.
http://www.doctohelp.com

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


Follow-Ups:

References:
Generating documentation for XML schema files: From: Cheryl Magadieu

Previous by Author: Re: change in careers
Next by Author: Re: Laptop for personal use?
Previous by Thread: Generating documentation for XML schema files
Next by Thread: Re: Generating documentation for XML schema files


What this post helpful? Share it with friends and colleagues:


Sponsored Ads