[DRAFT] Documentation API for W3C Markup Validators

Le 05-11-09 à 03:33, olivier Thereaux a écrit :
> On 9 Nov 2005, at 04:51, Karl Dubost wrote:
> 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.
> - drawings, maybe...  Thanks for the offer, but I am not sure...  
> Maybe other parts of our documentations would benefit from that?


* General comment:

The introduction is rough. We dive right into the dirty thing without  
much context. Which is always a bit difficult when we know that  
people access a Web page often coming from a search engine.

If I use a search engine I found usually this kind of things

Page Title                 Link
---------------------------------
Amazon.com Help            http://tinyurl.com/drova (Amazon has ugly  
URIs) ;)
Flick Services             http://www.flickr.com/services/api/
Google Web APIs            http://www.google.com/apis/
Technorati Developer       http://www.technorati.com/developers/
    Center
Yahoo! Developer Network   http://developer.yahoo.net/
    Home - Welcome!

For a more general list
  http://www.programmableweb.com/apis

They all almost have a small introduction.

* Technorati

[[[
The Technorati Developer Program helps power users and tool  
developers integrate Technorati data directly into their favorite  
applications. We provide an SDK, example scripts, a mailing list, and  
other helpful resources to assist your development process. Please  
join us and empower your users with the best possible experience  
using Technorati data.
]]]

* Google

[[[
Develop Your Own Applications Using Google

With the Google Web APIs service, software developers can query  
billions of web pages directly from their own computer programs.  
Google uses the SOAP and WSDL standards so a developer can program in  
his or her favorite environment - such as Java, Perl, or Visual  
Studio .NET.
]]]

* Yahoo

[[[
Innovate.
You bring the skills. We bring the ingredients.

Welcome to the Yahoo! Developer Network. We help software developers  
integrate their Web sites and applications with Yahoo! using standard  
technologies such as XML and RSS. Click on a link at left to learn  
more about our products and how we can help you.
]]]

* Flickr

On Yahoo
[[[
Introducing Flickr and the Flickr API

Flickr is a photo-sharing community that enables users to upload  
hundreds of photos and tag each photo with descriptive words. Other  
users can then search on these tags, enabling them to find and  
comment on the photos of other users. Flickr's active community and  
addictive sharing features have attracted millions of users. Even  
better, Flickr exposes a rich set of Web services that make the  
service highly hackable.
]]]

On Flickr Web site
[[[
The Flickr API is available for non-commercial use by outside  
developers. Commercial use is possible by prior arrangement.

For an example of an application built with this API, see Organizr  
(or here if you are already a Flickr member).
]]]

Sometimes the wording is quite marketing oriented, but they need to. :).

For example for Flickr there's a list of document to read in the  
first place,

Overview  http://www.flickr.com/services/api/misc.overview.html
Encoding  http://www.flickr.com/services/api/misc.encoding.html
…

and they expose the method names with a link to each of them, for  
example

flickr.photos.getInfo http://www.flickr.com/services/api/ 
flickr.photos.getInfo.html


> ## Markup Validator Web Service API
> SOAP 1.2 validation interface documentation


Just after the title and before the table of content
     I would remove "SOAP 1.2 validation interface documentation"
     and I would write.

[[[
About W3C  Markup Validator API

W3C Markup Validator is a Web service to encourage the validation of  
your Web documents (List of supported document formats). It exposes  
its Web service as a SOAP 1.2 interface, that you can use in your own  
applications.
]]]

Flickr gives a list of clients (API kits) in different languages  
(perl, java, python, etc.) implementing the access to the API. One  
funny thing though is that they put REST, SOAP and XML-RPC as 3  
different things.



> ### Validation Request Format
>
> Below is a table of the parameter you can use to send a query to  
> the W3C Markup Validator.
> If you want to use W3c's public validation server, use the  
> parameters below in conjunction with the following base URI:
> http://validator.w3.org/check
> (replace with the address of your own server if you want to call a  
> private instance of the validator.

[[[
### Requirement for using the Markup Validator

The W3C Markup Validation service is a free, public service for all.  
Use it with care for the benefit of the community.

1. When dealing with a batch of documents, You MUST wait at least 1  
second between each request.
2. Authentification for W3C Markup Validation service is NOT REQUIRED.


### List of parameters

The list of parameters are given with the assumption of a base URI.
     - using W3C Web service, the base URI is
         http://validator.w3.org/check
     - or the URI of your own local installation of the service.
]]]

I guess there's a missing example

[[[
- General case
http://validator.w3.org/check?parameter1=value1&parameter2=value2

_ Example for an EARL output of the W3C HomePage validation
http://validator.w3.org/check?uri=http://www.w3.org/&output=earl
]]]

The Table is confusing for example for uri, upload_file, and  
fragment. It seems it's another requirement: The minimum use of the  
service is a call with one these three methods.
     - uri
     - uploaded_file
     - fragment

So I guess if we want to make it more systematic, it will be  
something like. Could we consider that the W3C Markup Validator is a  
Web service with only one method (check)? and different parameters?

Template?

* Method name   (check)
     - Description
     - Arguments (uri, output, etc.)
         - Description
         - Possible Value
         - Example Response
         - Link to a real Example

I will write the description after your comments, if I'm not drifting  
too much. So let's check first if it makes sense.

-- 
Karl Dubost - http://www.w3.org/People/karl/
W3C Conformance Manager
*** Be Strict To Be Cool ***

Received on Friday, 11 November 2005 22:10:14 UTC