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:"Darren Barefoot" <darren -at- darrenbarefoot -dot- com> To:<techwr-l -at- lists -dot- raycomm -dot- com> Date:Thu, 15 Jan 2004 11:54:22 -0800
Check out the section starting on page 25 (of the digital file, page 17 in the printed). It provides examples of documenting several XML configuration files. As you can see, we basically made large tables and itemized each element that required explanation.
In terms of sample outputs, we do this all the time as well. It's a good idea, particular if your audience is developers and programmers. They tend to prefer an example that they can emulate or break down.
> -----Original Message-----
> From: bounce-techwr-l-124377 -at- lists -dot- raycomm -dot- com
> [mailto:bounce-techwr-l-124377 -at- lists -dot- raycomm -dot- com] On Behalf
> Of Jon Jacob Jinglehymerschmidt
> Sent: January 14, 2004 2:07 PM
> To: TECHWR-L
> Subject: Documenting an XML format -- how much detail?
>
<snip>
>
> What do you folks think?
>
> 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?
>
> -- TechWriterSF
>
