W3C home > Mailing lists > Public > public-qa-dev@w3.org > November 2005

Re: Web Service documentation (Was: WSDL for W3C Validators)

From: olivier Thereaux <ot@w3.org>
Date: Thu, 10 Nov 2005 16:28:57 +0900
Message-Id: <AB1AEB82-DE61-401E-8FBC-99E884693DA8@w3.org>
Cc: QA Dev <public-qa-dev@w3.org>, Yves Lafon <ylafon@w3.org>
To: Karl Dubost <karl@w3.org>


On 9 Nov 2005, at 17:33, olivier Thereaux wrote:
> Cool. Here's a start:
> http://dev.w3.org/cvsweb/validator/htdocs/docs/api.html
> visible at:
> http://qa-dev.w3.org/wmvs/HEAD/docs/api
>
> What it needs:
> - rewordings, clarifications, a fresh eye to assess whether the  
> document is understandable or not. Karl, if you want to be 1)  
> guinea pig and 2) reviewer, you're very welcome
> - some CSS magic to make the tables usable. The default table style  
> is fine for other parts of the validator site, but we should give  
> these reference tables a class and make them prettier.

The CSS I took care of today.

Karl offered to look at the document and compare it to other examples  
of "APIs" for popular web services, so that our document can be  
familiar to the hordes of developers. For having used the google API  
doc [1], I think ours is fairly similar. The amazon API I know a  
little, but their service seems much more complicated than ours - I  
can never find anything in it. Others (flickr[2], bloglines[3]) look  
similar in wording and presentation to what we're doing.

[1] http://www.google.com/apis/reference.html
[2] http://www.flickr.com/services/api/response.soap.html
[3] http://www.bloglines.com/services/api/

Karl, please ping me when you are done, so that I can open the  
document to a broader audience for review.

One thing we're still missing is a link to library implementations,  
but there are none yet :). I'm going to ping again Struan Donald, who  
made a perl library to use the markup validator's XML format, since  
he hasn't responded yet to my message [4].

[4] http://lists.w3.org/Archives/Public/www-validator/2005Oct/0092.html

-- 
olivier
Received on Thursday, 10 November 2005 07:29:10 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Thursday, 19 August 2010 18:12:46 GMT