Re: API Docs Proposal

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!


>
> * 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.


>
> * 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.

+Scott



>
>
> Chris Mills
> Opera Software, dev.opera.com
> W3C Fellow, web education and webplatform.org
> Author of "Practical CSS3: Develop and Design" (http://goo.gl/AKf9M)
>
> On 10 Jan 2013, at 02:01, Scott Rowe <scottrowe@google.com> wrote:
>
> > Hi all,
> >
> > From this week's general meeting I had the action item to develop a
> proposal for the API documentation.
> >
> > Please review this document and provide comments in this thread.
> >
> > The document is not complete, but it lays out the scope of the project
> and gets the ball rolling. I have not cited any external sources of
> documentation other than MDN, nor would I call complete either of the lists
> for documents to import or new documentation. Please provide any pointers
> to other sources of documentation and any new documentation that you think
> should be included.
> >
> > Could we also discuss this in the Thursday Content meeting - if we're
> still going to have it?
> >
> > Thanks!
> >
> > +Scott
> >
>
>