xml-dev - Re: documenting schemas/DTDs

["Simon St.Laurent" <simonstl@simonstl.com>]

At 06:16 AM 11/18/99 -0500, David Megginson wrote:
>"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.

I'll agree with both of you as well, though with the caveat that
conventions can make comments much more useful within DTDs.  XML Authority
does a little of this, but there's a lot more that can be done if people
are willing to take the time or develop tools.  So far, no one I've seen
has really invested in this, at least in a public way.

>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.

It seems like the schema spec might do well to provide a means of including
schema information inside of the documentation, rather than in a separate
box that goes along with the declarations (and which might never get filled
out.)  A transformation between this documentation-centric format and a
more machine-centric format probably wouldn't be that hard to create.

Speaking of these transforms, does anyone else think the schema spec is a
good target for profiling and simplification?

Simon St.Laurent
XML: A Primer, 2nd Ed.
Building XML Applications
Inside XML DTDs: Scientific and Technical
Sharing Bandwidth / Cookies
http://www.simonstl.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)