[XML-DEV Mailing List Archive Home] [By Thread] [By Date] [Recent Entries] [Reply To This Message] RE: Documenting DTD's
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@x...] 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.
|
PURCHASE STYLUS STUDIO ONLINE TODAY!Purchasing Stylus Studio from our online shop is Easy, Secure and Value Priced! Download The World's Best XML IDE!Accelerate XML development with our award-winning XML IDE - Download a free trial today! Subscribe in XML format
|