- From: Appelquist Daniel (UK) <Daniel.Appelquist@telefonica.com>
- Date: Mon, 29 Jul 2013 12:56:29 +0100
- To: Sergey Konstantinov <twirl@yandex-team.ru>, "www-tag@w3.org" <www-tag@w3.org>
- CC: Yehuda Katz <wycats@gmail.com>, Marcos Caceres <w3c@marcosc.com>, Anne van Kesteren <annevk@annevk.nl>, Alex Russell <slightlyoff@google.com>
Thanks for taking the initiative on this, Sergey - comments in-line: From: Sergey Konstantinov <twirl@yandex-team.ru> > > Hi, all. >Let me revive this discussion because I think it's really very important >part of our work. > >If nobody objects, I'd like to start working on the 4th topic: making a >guide for API design. > >As a first step I'm planning to: > (a) summarize goals and objectives for this guide, > (b) make the plan of the guide. >Should I use the github for that? Yes - the repo is set up for this already but is currently empty: https://github.com/w3ctag/api-design-guide Start in whatever format you want. We have so far only discussed content and form this guide should take at a high level in the TAG. I will put it on the agenda for this week's call. I think our current interaction with the audio group should be instructive, but we should now allow it to drive the boat too much, as this document should apply generally. I think the audience for this document includes people who are starting to write APIs who want a synopsis of the TAG's view. > >It seems helpful for now to collect your opinions on two subjects: > (a) a list of topics that should be covered by the guide, > (b) a list of examples, i.e. "good" APIs. > >I'd also appreciate your feedback on my article on making the APIs: > >http://konstantinov.cc/post/55163638512/maintaining-backwards-compatibilit >y >As per today's call, it seems time for us to consider next steps regarding >what concrete things we should be doing related to layering. As I see it, >there are some open questions about what the tag *can* do, as well as >what >it *should* do. > >Here's a (smallish) list of ideas, all or none of which we could pursue. >Looking for your ideas too, as I'm sure this list is missing quite a lot: > > - Create a more formal review process for specs. The >public-script-coord@threads are great, and it would be good if there >were a way for us to track > our progress in review and follow-up on specs that ask for it. A >nag-file > for follow-ups alone might be worth it's weight in gold. I think creating a review process is probably out of scope for this document (since the document should exist apart from any ongoing process) but should sit along side. > - A page that helps WG's that want to "do it right" learn a set of > concrete steps for how to engage best with us in helping to review >their > APIs early and most constructively. > - A page that lists the specific strengths of the TAG's membership so > that the right people can be pinged independently about issues. This >seems > obvious to us, but the world is a big place. > - A guide for how to design an idiomatic API in anger, including but >not > limited to: > - A discussion of imperative and declarative layering > - A library of common patterns to employ along with copy/paste-able > IDL and JS examples to show how they can be used > - A discussion on how and when to think about the JS library > ecosystem. > - Some common TAG-approved design principles to keep in mind when > considering how to formulate a feature's API surface area > - A concrete walkthrough of an API that starts declarative in v1 and > grows good, layered API later > - A walkthrough of an API that starts imperative and grows a > declarative expression in v2 > >What else? Is this list pitched at the wrong level? Dan
Received on Monday, 29 July 2013 11:57:22 UTC