Re: API Docs Proposal

Hi all,

I've updated the API project
proposal<http://docs.webplatform.org/wiki/WPD:Proposals/api_docs>and
the guide to creating
API pages <http://docs.webplatform.org/wiki/WPD:Creating_API_pages> with
guidance on converting and importing content.

It should be emphasized (so I'll do it here) that the goal for this project
is to bring the documentation for the APIs up to date and make WPD the most
current source for this documentation. So, while we are keen to use as much
extant and external content as we can, the source of truth continues to be
the standard specifications, and when editing the API pages, contributors
must check their work against the latest specifications. I've splattered
the above documents with words to that effect, as well. Splatter is my new
favorite word.

Ideally, authors of content from external sources, such as MDN, will not
only give their consent to have the content imported, but will also
continue to contribute updates to that content in its new location on WPD.
Maybe we can get these authors to help with this project and import their
own content (?). I can dream.

The next step is to reach out to those authors, starting with the authors
of the IndexedDB
<https://developer.mozilla.org/en-US/docs/IndexedDB>content on MDN.
These articles have a lot of MDN authors, a lot of Google
authors, and a lot of authors from all over, and it is one of the most
important, if one of the most reviled, APIs in the canon. The excellent
documentation on MDN may be credited with saving IndexedDB from oblivion.
So let's see if we can achieve the same level of excellence on WPD - with
IndexedDB and all of our APIs.

Janet is the original author of the IndexedDB API along with Google's Kevin
Lim, and she may have some insight into how we might go about requesting
permission from the long list of authors.

Janet, how would you recommend we proceed? Could you help me compose an
e-mail for the purpose and send it to the authors, or do you have something
else in mind?

Thanks!
+Scott





On Thu, Jan 10, 2013 at 10:20 AM, Chris Mills <cmills@opera.com> wrote:

>
> On 10 Jan 2013, at 17:38, Scott Rowe <scottrowe@google.com> wrote:
>
> > Thanks Chris,
> > My two bits in line...
> >
> >
> > On Thu, Jan 10, 2013 at 8:48 AM, Chris Mills <cmills@w3.org> wrote:
> > This all sounds really good.
> >
> > A few questions it brought to my mind.
> >
> > * Are the cited APIs that we've got in progress/documentation available
> for in any kind of priority order? Would it be worth doing that? This would
> help me to write the document covering work to do and priorities.
> >
> > The list of extant APIs is not prioritized - if it were, xhr wouldn't be
> last! I have added a priority column so that we can adjust and sort the
> order as we see fit. We started this without a eye toward priority - just
> to evaluate the problem and scope the work, but now we should establish
> priorities. Good call!
>
> Coolio.
>
> >
> >
> > * Are we going to cover JavaScript libraries such as jQuery, Raphael,
> etc. in the APIs section, or would that go in JavaScript, or somewhere
> separate? You are really just looking at HTML5 (and related/similar) APIs,
> which is not necessarily wrong, but I thought it was worth raising the
> question.
> >
> > I'm inclined to say that libraries are beyond the scope of this effort.
> There are so many, and most are documented well enough. Furthermore, the
> user of a library is more likely to get the documentation from the library
> itself. I think we should focus on HTML5 JavasScript APIs.
> >
>
> That seems reasonable.
>
> >
> > * On a similar note, are we going to cover 3rd party site APIs, such as
> Twitter, Flickr, etc.? Getting someone to write something concise and easy
> to follow about those could be a huge USP for us, for example I tried using
> the eBay API recently and I gave up because the documentation was
> completely unusable. But then again, how many people such APIs? Is the
> demand there, or would it just be a waste of effort? There are obviously
> much lower hanging fruit than that to get started with.
> >
> > Again, and for similar reasons, I think this is out of scope. However,
> we could consider reaching out to 3rd parties to get them to publish their
> docs on WPD.
>
> And again, sounds reasonable.