Re: API Docs Proposal

In my priorities list for the topics/tasks leading up to alpha/beta, APIs is definitely going to be lower down the priority list than css and html, but APIs are incredibly popular and sought after info, so I don't think they should be that far off. Scott can carry this forward as a personal area of interest, and at least organize the sub topic pages with stubs, etc. 

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 18:16, Jonathan Garbee <jonathan@garbee.me> wrote:

> Let's leave frameworks out of the documentation scope until later, if ever.
> It needs more discussion and add features to the sure and we have enough to deal with at the moment.
> 
> -Garbee
> 
> On Jan 10, 2013 12:38 PM, "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!
>  
> 
> * 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
> >
> 
> 
>

Received on Thursday, 10 January 2013 18:20:58 UTC