RE: Documenting DTD's

["Bullard, Claude L (Len)" <clbullar@ingr.com>]

It depends on the project and the people.  In some
cases, the doc people are developing the DTD.  In 
others, they are skilled and talented enough to 
read the specs.  You do have specs, right?

It just isn't that hard, and frankly, hiring a 
technical writer with only typing, spelling 
and Winhelp skills isn't that good a hire and 
they will become boat anchors keeping the rest 
of the organization behind the learning curve.  
If you do have such, pay them like a secretary. When 
the real secretary finishes the nighttime database course 
(How hard is MS Access?), give the secretary 
the higher wage and the technical writer's job.

http://www.xmlspy.com/images/shots/ide40large.gif

Looks like a diagram to me, but maybe that is the
document.

If a parser strips comments, get another parser. 
Schemas have annotations, appinfo, and all of that. 
Use it when you think you need the extra support. 
Otherwise <!-- --> works in the interim.

This technology was originally designed to bridge 
the chasm between the well-trained programmer and 
the semi-computer literate.  If it has been pushed 
so far to the side of the programmer that the other user 
can no longer decipher it, we have made a very big 
mistake adopting XML.

Len 
http://www.mp3.com/LenBullard

Ekam sat.h, Vipraah bahudhaa vadanti.
Daamyata. Datta. Dayadhvam.h


-----Original Message-----
From: XML Everywhere [mailto: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.