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: "Mike O." <obie1121 -at- yahoo -dot- com>
Date: Thu, 15 Jan 2004 21:42:40 -0800 (PST)


--- "Mike O." <obie1121 -at- yahoo -dot- com> wrote:
>
> Jon Jacob Jinglehymerschmidt wrote:
>
> > Has anyone here had to document an XML interface?
>
> Yes, here are some suggestions:
>
> - Make sure you provide a library of sample code
> that shows input and
> output.

I agree. Sample code is a must.

>
> - Provide an online test server where your audience
> can cut-and-paste your
> sample input, submit it, and get the same output as
> in your sample output.
> Then they can modify the code and use the test
> server to test their own new
> code.

Yes, yes, and yes.

[snip]
>
> - For each element and attribute, write a good
> description of its purpose,
> how it is useful, and what happens when you submit
> it to your server.

You can use the xs:documentation element and then use
xi:include in you document to "suck" the value into
your document during transformation.

There are also other techniques such as Norman Walsh's
weave.xsl


Sean Wheller

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




Previous by Author: Re: Documenting an XML format -- how much detail?
Next by Author: Re: Context sensitivity and help produced from XML
Previous by Thread: Re: Writing Costs Worldwide
Next by Thread: Subscription Change


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


Sponsored Ads