Re: Human readable documentation of services ?

My experience is limited to the geospatial services and metadata world 
and metadata for navigation of federations of websites... however I 
would posit that:

* metadata that isnt actually exercised by the person entering the data 
tends to be, as we Aussies say "ordinary" - other more scatalogical 
terms apply :-)
 - this "exercising" may be having the metdata used to drive feedback 
via the presentation of a web page and navigation links in a preview step
- alternatively knowing someone will be coming asking for clarification 
in the next few weeks if they dont do it right!

* documentation is not a scalable mechanism in its own right - you 
really need classification via controlled vocabularies - I.e. the human 
readable view of an ontology.
  -analysis of interoperability requirements in spatially-explicit 
domains highlights that the governance model of the vocabulary is the 
root of the semantics - users are thus looking for "well known" 
references that are semantically explicit and useful. Nobody will read 
free form "documentation" and trust it without strict control over its 
content and meaning.

So, IMHO you are on the right track about the need for another layer of 
documentation to make the syntactical schemas work in practice, however 
I think that at most the documentation should be harvested from an 
external source that can be dereferenced by the declared object types. 
This external source would be the artefact you would query to find or 
understand the nature of the service.

Unfortunately, this is no longer a computational problem, but a social 
one, and you need a wider set of skills and influence to make any impact 
on it - which is why all the Computing Science 101 - Web Services 
examples gloss it over.

Rob Atkinson
CTO
Social Change Online
(- another recycled mathmetician !)

Paul Libbrecht wrote:

>
>     
> Dear WSers,
>
> I've been searching and asking but I have not, yet, met some  
> standardized practice to document a web-service or a composite  
> thereof... I would have expected this be widely accepted and used  
> but... all I see is that documentation slots exist in most  
> ws-description schemas (at least in OWL-S and WSDL) but are not...  
> used...
>
> I would have expected that something like javadoc would have been  
> easily made accessible... any other experience ?
>
> thanks
>
> paul
> ------------------------------------------------------------------------ 
> ---
> - http://www.activemath.org/~paul -paul libbrecht- recycled  
> mathematician -
>

Received on Friday, 12 November 2004 23:40:28 UTC