Re: Documenting an XML format -- how much detail?

Subject: Re: Documenting an XML format -- how much detail?
From: Sean Wheller <seanwhe -at- yahoo -dot- com>
To: Goober Writer <gooberwriter -at- yahoo -dot- com>
Date: Thu, 15 Jan 2004 21:37:30 -0800 (PST)


--- Goober Writer <gooberwriter -at- yahoo -dot- com> wrote:
>
> > that's nice and all, but some (10-30%) of the
> users
> > will need to read/parse the XML data directly.
>
> Document the nuts and bolts so they can do so. Don't
> document the schema (it should be self-documenting)
> but do tell those 10-30% users in your documentation
> to look at the schema for "advice".

This is sound advice. An XML Instance an its XML
Schema are self documenting.

>
> > Are there "standard practices" for this? I'm
> > delighted
> > to write a lot or a little (I get paid either
> way).
> > But what's the ***expectation*** in the XML
> > community
> > with respect to documenting the XML other than
> just
> > handing them the XML schema file?

From the developer perspective. They at best want the
XSD and perhaps it should use the xs:documentation and
xs:annotation elements.

<hint>
<para>Do take a look at
http://titanium.dstc.edu.au/xml/xs3p/
</para>
</hint>

Sean Wheller

__________________________________
Do you Yahoo!?
Yahoo! Hotjobs: Enter the "Signing Bonus" Sweepstakes
http://hotjobs.sweepstakes.yahoo.com/signingbonus




References:
Re: Documenting an XML format -- how much detail?: From: Goober Writer

Previous by Author: FrameMaker International
Next by Author: Re: Documenting an XML format -- how much detail?
Previous by Thread: Re: Documenting an XML format -- how much detail?
Next by Thread: RE: Documenting an XML format -- how much detail?


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


Sponsored Ads