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 Subsetof a W3

[ Lists Home | Date Index | Thread Index ]

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

just musing...

Database theory makes a pretty strong case that redundance in functionally dependent data elements leads to update anomalies. In practice, this is the case even when a development organization makes strenuous efforts to properly maintain and update the documents. Either the code or the document breaks, or both, on a more or less regular basis. 

That's also why distinguishing uses like 
<ProductPartIdentifier UID="9_5.8">123-456-789</ProductPartIdentifier>

is important. It goes towards whether I can impose my own local editing, processing, and updating processes without recourse to some third party, whether and whose ideas of "universal identifiers" I use in my own systems, and whether or not I can work with someone else whose ideas of "universal" differ from my own. 




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

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