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

Subject: Re: Documenting an XML format -- how much detail?
From: Goober Writer <gooberwriter -at- yahoo -dot- com>
To: Jon Jacob Jinglehymerschmidt <techwritersf -at- yahoo -dot- com>, TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 15 Jan 2004 08:39:40 -0800 (PST)

> 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".

> 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?

Those who know XML well will probably grab the schema
and be on their way. Others who are newbies to XML
might need hand-holding. I suggest documenting best
practices and explain how the product is INTENDED to
be used.

Not to sound crude, but if they need more help, they
can always purchase training or consulting services
from your company. It's not unheard of, and certainly
isn't a bad thing for your company or your users who
require more TLC.

=====
Goober Writer
(because life is too short to be inept)

"As soon as you hear the phrase "studies show",
immediately put a hand on your wallet and cover your groin."
-- Geoff Hart

We can't all be as creative with sigs as krautgrrl. ;-)

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




Follow-Ups:

References:
Documenting an XML format -- how much detail?: From: Jon Jacob Jinglehymerschmidt

Previous by Author: Re: Writing Costs Worldwide
Next by Author: Re: A survey on Technical Communicators on Cross-Functional Teams
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