Document Schemas and Documentation (was: RE: XML and (K)Office)

[David Megginson]

Simon St.Laurent writes:

 > >And what, pray tell, part of a DTD helps you "make sense" of a
 > >format? -Tim
 > 
 > The comments, of course!  (Which is a large part of why DDML provided
 > explicit space for documentation.)

Ain't that the truth.  As I pointed out to the DDML designers a while
back, though, every XML element and attribute needs three types of
documentation:

1. an XML 1.0 element or attribute name (i.e. "a");
2. a human-readable title (i.e. "Hypertext Anchor"); and
3. a proper description (probably including paragraphs, examples,
   tables, etc.).

Some people might also add a brief, one-sentence description
in-between (2) and (3).  Items (2) and (3) also need to be
localizable, possibly by allowing repetition coupled with xml:lang.


All the best,


David

-- 
David Megginson                 david at megginson.com
           http://www.megginson.com/

xml-dev: A list for W3C XML Developers. To post, mailto:xml-dev at ic.ac.uk
Archived as: http://www.lists.ic.ac.uk/hypermail/xml-dev/ and on CD-ROM/ISBN 981-02-3594-1
To (un)subscribe, mailto:majordomo at ic.ac.uk the following message;
(un)subscribe xml-dev
To subscribe to the digests, mailto:majordomo at ic.ac.uk the following message;
subscribe xml-dev-digest
List coordinator, Henry Rzepa (mailto:rzepa at ic.ac.uk)