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:"Mark Baker" <listsub -at- analecta -dot- com> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Thu, 15 Jan 2004 10:48:02 -0500
Jon Jacob Jinglehymerschmidt wrote:
>some (10-30%) of the users
> will need to read/parse the XML data directly.
>
> The question is: how much should the "developer
> documentation" document? One could argue that anyone
> who cares should just read the XML Schema.
The XML Schema will not contain the information necessary to interpret the
file. A schema only governs the content model of an XML language, not its
semantics. If users have to interpret the XML document than you need to tell
them what the markup means. In some cases, the meaning of the markup can be
deduced from the naming of elements, but this should never be relied upon.
You need to tell people what each element means, and what each significant
combination of elements means.
As always, however, the answer to what documentation is required is not
found in the specifics of the technology but in the specifics of the user's
tasks. Ask what the user needs to do with this product, then ask what
information they need in order to complete that task.
