Re: Next steps on layering?

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