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

Hi Linda,

Thanks.

It would be great if you could review.

Best
Ig

2016-03-30 10:49 GMT-03:00 Linda van den Brink <l.vandenbrink@geonovum.nl>:

> Dear Ig,
>
>
>
> Sounds very good. Let me know if you need me to review or whatever!
>
>
>
> Linda
>
>
>
> *Van:* Ig Ibert Bittencourt [mailto:ig.ibert@gmail.com]
> *Verzonden:* woensdag 30 maart 2016 15:43
> *Aan:* Phil Archer
> *CC:* public-sdw-comments@w3.org
> *Onderwerp:* 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.
>



-- 

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.