RE: [xml-dev] reaching humans (was Re: [xml-dev] Extract A Subset of a W3C XML Schema?)

[David Megginson <david@megginson.com>]

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

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