Re: Next steps on layering?

I've commited the proposal for Guide structure.
https://github.com/w3ctag/api-design-guide/blob/master/API%20Design%20Guide.md
Comments are welcome.

P.S. Feel free to point out my grammatical errors for I'm not a native speaker.

29.07.2013, 15:57, "Appelquist Daniel (UK)" <Daniel.Appelquist@telefonica.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

-- 
Konstantinov Sergey
Yandex Maps API Development Team Lead
http://api.yandex.com/maps/

Received on Thursday, 1 August 2013 13:41:56 UTC