xml-dev - Re: documenting schemas/DTDs

[David Megginson <david@megginson.com>]

"W. Eliot Kimber" <eliot@isogen.com> 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@megginson.com
           http://www.megginson.com/

xml-dev: A list for W3C XML Developers. To post, mailto:xml-dev@ic.ac.uk
Archived as: http://www.lists.ic.ac.uk/hypermail/xml-dev/ and on CD-ROM/ISBN 981-02-3594-1
To unsubscribe, mailto:majordomo@ic.ac.uk the following message;
unsubscribe xml-dev
To subscribe to the digests, mailto:majordomo@ic.ac.uk the following message;
subscribe xml-dev-digest
List coordinator, Henry Rzepa (mailto:rzepa@ic.ac.uk)