[XML-DEV Mailing List Archive Home] [By Thread] [By Date] [Recent Entries] [Reply To This Message]

Re: reaching humans (was Re: Extract A Subsetof a W3

• To: David Megginson <david@m...>
• Subject: Re: reaching humans (was Re: Extract A Subsetof a W3C XML Schema?)
• From: Mitch Amiano <mamiano@n...>
• Date: Fri, 01 Aug 2003 10:21:30 -0400
• Cc: xml-dev@l...
• In-reply-to: <16170.20891.294093.545697@m...>
• Organization: Software Adjuvant
• References: <5FC285666E68F542A3F8A0E8693BC41A02F173@c...> <r02000000-1026-E093B245C3AF11D794470003937A08C2@[192.168.124.11]> <16170.20891.294093.545697@m...>
• Reply-to: mitch.amiano@s...
• User-agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US; rv:1.4b) Gecko/20030507

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>
from 
<UDEF_9_5_8>123-456-789</UDEF_9_5_8>

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. 

Regards,

Mitch

• References:
  • RE: reaching humans (was Re: Extract A Subset of a W3C XML Schema?)
    • From: David Megginson <david@m...>

• Prev by Date: RE: How did "public identifier" get its name...
• Next by Date: Re: Extract A Subset of a W3C XML Schema?
• Previous by thread: Re: reaching humans (was Re: Extract A Subset of a W3C XML Schema?)
• Next by thread: RE: How did "public identifier" get its name...
• Index(es):
  • Date
  • Thread