TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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. ;-)
