RE: Documenting DTD's

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

Fire her.  

She is whining you out of business just as 
surely as a programmer refusing to document code.  
There is absolutely no excuse for not commenting a 
DTD or schema.

Yes.  Near and Far generates pictures.  XMLSpy generates 
pictures. Almost any decent schema design tool does it 
now.

But do put that help writer back in the unemployment line 
at least until she stops whining about the job she is 
paid to do.  

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

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


-----Original Message-----
From: Bob Wait [mailto:BWait@ariba.com]
Sent: Thursday, June 14, 2001 3:39 PM
To: 'xml-dev@lists.xml.org'
Subject: Documenting DTD's


I just spent a half hour listening to our docs/help person complain about
the uselessness of generating documents containing english language
descriptions of elements defined in DTDs.  As soon as she writes the stuff
it's obsolete or vague, and why should she be a middlewoman adding little
additional real value between the DTD writer and the DTD consumer, etc.

So, two questions for the list: a) is there a javadoc-like standard for
adding comments to DTDs and a set of tools out there for extracting them
and, better, b) is there a tool out there that will read a DTD and produce a
decent picture of the elements and their relationships?  I'm sure there must
be something out there we could leverage before we roll our own...

b

PS And of course I'm interested in anyone's experience/thoughts on
generating and maintaining useful documentation for DTDs.