Re: Next steps on layering?

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?

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-compatibility

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

Received on Monday, 29 July 2013 09:27:07 UTC