OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help



   RE: [xml-dev] reaching humans (was Re: [xml-dev] Extract A Subset of a W

[ Lists Home | Date Index | Thread Index ]
  • To: xml-dev@lists.xml.org
  • Subject: RE: [xml-dev] reaching humans (was Re: [xml-dev] Extract A Subset of a W3C XML Schema?)
  • From: David Megginson <david@megginson.com>
  • Date: Fri, 1 Aug 2003 07:40:11 -0400
  • In-reply-to: <r02000000-1026-E093B245C3AF11D794470003937A08C2@[]>
  • References: <5FC285666E68F542A3F8A0E8693BC41A02F173@corpmail01.mygazoo.com><r02000000-1026-E093B245C3AF11D794470003937A08C2@[]>

Simon St.Laurent writes:

 > Second, that kind of markup is only useful until we can't find the
 > documentation any more.  For cases where the documentation is always
 > going to be absolutely positively necessary, maybe that's fine.

Apologies if this point has already come up (and I've missed it), but
it's worth noting how the software world has been creeping towards
integrated documentation in source code for some time.  There were
many early models, such as Knuth's Literate Programming, documentation
lines in eLISP functions, and Perl's POD, but integrated API
documentation really seized the collective imagination of coders with
JavaDoc, something is now much imitated in C++.

In theory, there is no reason that API documentation cannot be
separate from the programming code; in practice, (a) it never gets
properly maintained and updated, and (b) as Simon mentions, it often
gets lost.  The same thing lesson to XML -- making an XML document
partly self-documenting is always a good thing.

All the best,


David Megginson, david@megginson.com, http://www.megginson.com/


News | XML in Industry | Calendar | XML Registry
Marketplace | Resources | MyXML.org | Sponsors | Privacy Statement

Copyright 2001 XML.org. This site is hosted by OASIS