Cart
[Home] [By Thread] [By Date] [Recent Entries]
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.
|
