Lists Home |
Date Index |
- From: David Megginson <email@example.com>
- To: "'firstname.lastname@example.org'" <email@example.com>
- Date: 18 Nov 1999 06:16:56 -0500
"W. Eliot Kimber" <firstname.lastname@example.org> 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.
> 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
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 Megginson email@example.com
xml-dev: A list for W3C XML Developers. To post, mailto:firstname.lastname@example.org
Archived as: http://www.lists.ic.ac.uk/hypermail/xml-dev/ and on CD-ROM/ISBN 981-02-3594-1
To unsubscribe, mailto:email@example.com the following message;
To subscribe to the digests, mailto:firstname.lastname@example.org the following message;
List coordinator, Henry Rzepa (mailto:email@example.com)