Re: API Docs Proposal

Wonderful! Thanks Lance!!! These are really nice docs. If we follow suit on
WPD, drawing on the MDN materials and Lance, maybe we'll be so successful
that the working group will pluck up the courage to implement the
SYNCHRONOUS API  :)   - I have a dream!
+Scott




On Tue, Jan 22, 2013 at 4:39 PM, Eliot Graff <Eliot.Graff@microsoft.com>wrote:

>  Hi Scott.****
>
> ** **
>
> For the IndexedDB content, Lance Leonard is willing to help bring content
> together and flesh out the story around the API. Lance has worked with me
> as I edited the IndexedDB spec and has written widely about it. [1, 2]****
>
> ** **
>
> Thanks,****
>
> ** **
>
> Eliot ****
>
> ** **
>
> [1] http://msdn.microsoft.com/en-us/library/jj154908.aspx****
>
> [2] http://msdn.microsoft.com/en-us/library/ie/hh673548(v=vs.85).aspx****
>
> ** **
>
> *From:* Scott Rowe [mailto:scottrowe@google.com]
> *Sent:* Tuesday, January 22, 2013 1:49 PM
> *To:* Janet Swisher
> *Cc:* public-webplatform@w3.org
> *Subject:* Re: API Docs Proposal****
>
> ** **
>
> Terrific Janet, thanks!****
>
> ** **
>
> I've established this spreadsheet <http://goo.gl/RpHYQ> to track
> permissions on pages, starting with the IndexedDB<https://developer.mozilla.org/en-US/docs/IndexedDB>pages. For most of the contributors I was unable to find an e-mail address,
> but I'm assuming that as an MDN Admin, you'll be able to get that
> information.****
>
> ** **
>
> I've also taken a swing at an e-mail to send to contributors to ask their
> permission:****
>
> ** **
>
>  Dear MDN Contributor,****
>
> ** **
>
> Could we have your permission to copy, either in-part or in-whole, text
> you contributed to the following articles on the Mozilla Developer Network?
> ****
>
> ** **
>
> [links to articles]****
>
> ** **
>
> We would like to use this information for the next updated version of the
> documentation, to be located on WebPlatform.org, also known as Web
> Platform Docs <http://docs.webplatform.org/wiki/Main_Page> (WPD).****
>
> ** **
>
> WPD is a community collaboration with Mozilla, Microsoft, Google, Opera,
> Adobe, HP, Nokia, facebook, Intel, and the W3C. It aims to be the main
> source of documentation for standards-based web development.****
>
> ** **
>
> We need your permission to re-use content from MDN. Once you grant your
> permission, community members can copy your writing to WPD, and that
> content will be attributed to MDN, according to our guidelines for external
> attribution <http://docs.webplatform.org/wiki/WPD:External_Attribution>.**
> **
>
> ** **
>
> We'd also love to have you join us and continue to contribute content to
> WPD. Thanks for helping to move the Web forward!****
>
> ** **
>
> Sincerely,****
>
> ** **
>
> Web Platform Docs ****
>
> ** **
>
> Any help you (or anyone) can lend with this composition I would greatly
> appreciate!****
>
> ** **
>
> I'll look into creating a patch to track permissions on MDN, maybe I can
> find someone to help.****
>
> ** **
>
> +Scott****
>
> ** **
>
> ** **
>
> On Thu, Jan 17, 2013 at 11:56 AM, Janet Swisher <jswisher@mozilla.com>
> wrote:****
>
>   On 1/12/13 3:25 PM, Scott Rowe wrote:****
>
>  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.****
>
>   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?****
>
>
> In the short term, we can compose an email to the authors, which I can
> send, and we'll need to manually track responses.
>
> In the long term, a few things would be helpful:
> * A way for MDN users to easily declare that their content can be reused
> under WPD's terms.
> * A (privacy-protected) way for MDN users to contact each other (so you
> can ask somebody to give consent).
> * A way to track which contributors to a page have given consent for WPD
> reuse.
>
> I have submitted a bug for adding fields to MDN user profiles to indicate
> consent to reuse content in WPD:
> https://bugzilla.mozilla.org/show_bug.cgi?id=830514
>
> This is a fairly small change, code-wise, but also pretty low priority
> relative to other things that are needed on MDN. The quickest way to get it
> done may be for someone outside the MDN dev team to submit a patch. All the
> code for MDN is on github (https://github.com/mozilla/kuma) and is
> written in Python/Django. The MDN dev team hangs out on #mdndev on
> irc.mozilla.org, and they are quite friendly.
>
> Intra-site messaging on MDN is high on our development priority list
> anyway, but it will take some time to spec and code, and it is still behind
> a few other things in priority. In the meanwhile, if you want to contact an
> MDN user, please work through me or another MDN admin (such as Eric
> Shepherd).
>
> The per-page tracking isn't on the radar yet, but I'll submit a bug for
> it, and make it dependent on the profile bug.****
>
>
>
>
> ****
>
>  ** **
>
> ** **
>
> 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.****
>
>  ** **
>
> ** **
>
> -- ****
>
> Janet Swisher <jREMOVEswisher@mozilla.com>****
>
> Mozilla Developer Network <https://developer.mozilla.org> ****
>
> Technical Writer/Community Steward****
>
>  ** **
>