Re: RE: [DWBP + SDW: API] Related Best Practice

Dear Linda,

Thank you for your feedback.

In think we could improve the description of the DWBP:BP 27 (yes, now it is
BP 27 [1]) by adding the details you proposed in your e-mail and also by
adding about "the time to first successful call". In the beginning of the
documentation, this is very well presented [2] :


   - *API documentation is the first clue to your developer customer about
   the quality and usefulness of the API. When API documentation is complete
   and easy to understand, developers are probably more willing to continue
   their journey implementing it. One important aspect here is the Time To
   First Successful Call (TTFSC). Being capable of doing a successful request
   to the API within a few minutes will increase the chances that the
   developer will stick to your API.*

I also lik the examples described in the SDWBP 29, which could be merged.


@Phil - sorry about that. Now it is in the public-comments list. :-)


[1] http://w3c.github.io/dwbp/bp.html#documentYourAPI
[2] https://github.com/geo4web-testbed/topic3/wiki/Developer-Experience

Best
Ig

2016-03-29 5:55 GMT-03:00 Phil Archer <phila@w3.org>:

> For archive
>
>
> -------- Forwarded Message --------
> Subject: RE: [DWBP + SDW: API] Related Best Practice
> Date: Tue, 29 Mar 2016 08:34:05 +0000
> From: Linda van den Brink <l.vandenbrink@geonovum.nl>
> To: Ig Ibert Bittencourt <ig.ibert@gmail.com>, jeremy.tandy@gmail.com <
> jeremy.tandy@gmail.com>, p.barnaghi@surrey.ac.uk <p.barnaghi@surrey.ac.uk>,
> Bernadette Farias Loscio <bfl@cin.ufpe.br>, Caroline Burle <cburle@nic.br>,
> Newton Calegari <newton@nic.br>, Phil Archer <phila@w3.org>
>
> One link I forgot to supply with my answer, about API documentation and
> time to first successful call:
> https://github.com/geo4web-testbed/topic3/wiki/Developer-Experience
>
> Van: Linda van den Brink
> Verzonden: dinsdag 29 maart 2016 10:30
> Aan: 'Ig Ibert Bittencourt'; jeremy.tandy@gmail.com;
> p.barnaghi@surrey.ac.uk; Bernadette Farias Loscio; Caroline Burle; Newton
> Calegari; Phil Archer
> Onderwerp: RE: [DWBP + SDW: API] Related Best Practice
>
> Dear all,
>
> I think that indeed DWBP 26 and SDWBP 29 could be merged. I reviewed DWBP
> 26 and compared it to SDWBP 29. I think that SDWBP 29 might even be
> completely removed from the SDWBP, as there are no special spatial aspects
> in it (some examples aside), and DWBP 26 describes the issue sufficiently.
> However in SDWBP 29, there is currently a little more detail you could
> consider adding to DWBP 26. What I’m missing is:
>
> -          API documentation should describe the data(set) it exposes
>
> -          We recommend providing machine readable API documentation that
> can be used by software development tools to help developers build API
> client software. (or is that what you mean by self-documenting?)
>
> -          Where a parameter domain is bound to a set of values (e.g.
> value range, spatial or temporal extent, controlled vocabulary etc.), the
> API documentation or the API itself should indicate the set of values that
> may be used in order to help users request data that is actually available.
>
> An extra thing you could add, if you want, is a statement I learned from
> one of the participants of a testbed on data on the web we recently held.
> He said that a good measure for knowing if an API is well-documented is
> ‘the time to first successful call’.
>
> I hope this helps, my fellow SDW editors might also want to respond.
>
> Linda
>
> Van: Ig Ibert Bittencourt [mailto:ig.ibert@gmail.com]
> Verzonden: maandag 28 maart 2016 18:07
> Aan: jeremy.tandy@gmail.com<mailto:jeremy.tandy@gmail.com>;
> p.barnaghi@surrey.ac.uk<mailto:p.barnaghi@surrey.ac.uk>; Linda van den
> Brink; Bernadette Farias Loscio; Caroline Burle; Newton Calegari; Phil
> Archer
>
> Onderwerp: [DWBP + SDW: API] Related Best Practice
>
> Dear Editors of the Spatial Data on the Web Best Practices Document,
>
> My name is Ig Bittencourt and I am a member of the W3C Data on the Web
> Working Group. Two weeks ago we had our final F2F meeting and we discussed
> about our BP Doc [1]. In one of the discussions, we realized that SDW:BP 29
> [2] is very related to DWBP:BP 26.
>
> Both BPs are related to documenting APIs. However, in SDW:BP 29, there is
> a special atention on the self-description of APIs. However, if you look at
> the intended outcome of DWBP:BP 26, we discuss a little about it.
>
> For this reason, we started to wonder if these BPs could be merged.
> Please, let us know what do you think about this possibility.
>
> All the very best,
>
> [1] http://w3c.github.io/dwbp/bp.html
> [2] http://w3c.github.io/sdw/bp/#self-describing-apis
> [3] http://w3c.github.io/dwbp/bp.html#documentYourAPI
>
>
> Ig Ibert Bittencourt
> Professor Adjunto III - Instituto de Computação/Universidade Federal de
> Alagoas (UFAL)
> Vice-Coordenador da Comissão Especial de Informática na Educação
> Líder do Centro de Excelência em Tecnologias Sociais
> Co-fundador da Startup MeuTutor Soluções Educacionais LTDA.
>
>
>
>


-- 

Ig Ibert Bittencourt
Professor Adjunto III - Instituto de Computação/Universidade Federal de
Alagoas (UFAL)
Vice-Coordenador da Comissão Especial de Informática na Educação
Líder do Centro de Excelência em Tecnologias Sociais
Co-fundador da Startup MeuTutor Soluções Educacionais LTDA.