Re: documenting schemas/DTDs
"W. Eliot Kimber" <eliot@i...> writes: > My personal feeling, based on many years of painful experience > developing and maintaining DTDs of varying scale and complexity and > documenting same (including the original version of IBM's IBM ID Doc > application and the second edition of the HyTime architecture, both > massive documentation projects) is that the only practical way to > develop and manage non-trivial document types is by making the > documentation the primary definition, with the working declarations > extracted from it using some sort of make process. [snip] > If you are are creating DTD-syntax DTDs, the syntax of DTDs is simply > not up to the task of maintaining and managing documentation of any > useful sophistication. I agree very strongly with Eliot, perhaps because we both have a lot of experience in creating (rather than just processing) user documentation. Even a schema spec that allowed very rich documentation in each declaration would be at best the equivalent of JavaDoc, and that's not good enough. The problem (and this is a classic in tech writing) is that the optimal way to arrange information for a human reader is rarely the optimal way to arrange information for technical implementation, and vice versa. Except in very rare circumstances, for example, any tech writer who structures a user manual around the UI ("Chapter 1: the File Menu") deserves to be fired without severance pay, ritually humiliated in front of the whole office, and rolled all the way out to the parking lot in a garbage can -- the fact that they aren't is a testimony to the shortage of even minimally competent tech writers out there. Personally, I deserve the same treatment for never having provided a proper SAX 1.0 spec -- I'll try to remedy that situation before everyone figures out how to send a garbage can through e-mail. All the best, David -- David Megginson david@m... http://www.megginson.com/ xml-dev: A list for W3C XML Developers. To post, mailto:xml-dev@i... Archived as: http://www.lists.ic.ac.uk/hypermail/xml-dev/ and on CD-ROM/ISBN 981-02-3594-1 To unsubscribe, mailto:majordomo@i... the following message; unsubscribe xml-dev To subscribe to the digests, mailto:majordomo@i... the following message; subscribe xml-dev-digest List coordinator, Henry Rzepa (mailto:rzepa@i...)
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