Re: Documenting DTD's

[XML Everywhere <host@xmleverywhere.com>]

A DTD is a contract.  If a DTD is
in flux, the doc people should
not be involved until later
in the development cycle.  Otherwise,
devs and docs are both going to
get peeved.

Developers should write the initial
documentation for DTDs,
not doc people.  Doc people
can make the docs pretty,
clean up grammar, and provide
examples.  Describing a DTD to
a doc person verbally (or worse,
handing them an undocumented
DTD) is generally not very effective.  Just try
that with HTML.  It's just tag
soup and unless the doc
person has access to the
application (e.g., a browser), 
DTDs are pretty difficult
to decipher.

But generally the docs that developers write aren't
very easy to follow.  Once the DTD is
finalized, doc people can do a lot
in making the documentation easier
to understand, mainly via examples.

As far as tools go, I don't think
XML Spy can graphically
represent DTDs  (at least I 
haven't found that feature).   
Extensibility (or whatever name 
its new owner gave it) does.
XML Spy does show XSDs graphically.

I believe XSDs support comments and
annotations directly in the model.  
DTDs require text to be added 
in XML-style comment blocks (<!-- -->)
and there are lots of places
where parsers don't allow comments,
which is a pity.  So with DTDs you are almost always
forced to make the documentation
external.  We put the documentation
in HTML format.