xml-dev - Re: documenting schemas/DTDs

[Len Bullard <cbullard@hiwaay.net>]

David Megginson wrote:
> 
> > 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.

I also agree with Eliot.  On the other hand, when handed thousands 
of pages of SGML for the C-130 to convert, it took both the comments 
and the structural validation capabilities to make the translation, 
and that was SGML to SGML.  

It isn't that DTDs are the end all tool, they are just a very useful 
one and common experience bears that out particularly where the people 
doing the work aren't computer scientists or consultants.  The joy of 
using it is the EASE of using it.

Without the comments, it was a best guess affair; without the 
declarations, it was hopeless.

len



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)