What should be the goals of creating an open discussion around an API spec?

[matin]

I'm moving part of the conversation that started in #1 here.

Here are the goals that I want to achieve:

• Make the reasoning behind API design decisions public. Even if the community doesn't comment, there's still value in discussing openly
• Give stakeholders outside of the Balanced team to comment and challenge decisions, ask for clarifications in the docs and spec, or suggest enhancements in the API
• Keep Balanced honest by ensuring the API is consistent with publicly published specifications. Balanced has a relatively small team, and it allows us to self police without requiring a manual process to guarantee consistency across the spec and docs

/cc @whit537 @mahmoudimus

[matin]

Opening up the conversation to HN: http://news.ycombinator.com/item?id=4398340

[matin]

ping @ajsharp @khussein @bcm @alexnotov @jkatz @gangster @davidgrieser @ihunter @obfuscat3d

[jmathai]

Love this. What we did for OpenPhoto's API was to have drafts on the Github Wiki and open it up for comments. Sometimes we'd get comments and other times we didn't.

The most valuable part isn't the contributions you get but the benefit of including your users in the discussion. That goes a long way (as you hinted at).

[zealoushacker]

👍 loves it. Also, definitely agree with your decision to use reST for the API spec, given the alignment of the clear advantages and your goals.

[matin]

It's become clear that the primary value of this approach is exposing the reasoning behind different decisions by the Balanced team, being open about progress/timelines, and giving everyone the ability to be involved in decisions.

[ajsharp]

+1 love what you guys are doing here.

• Alex

On Sep 17, 2012, at 1:13 PM, Matin Tamizi [email protected] wrote:

It's become clear that the primary value of this approach is exposing the reasoning behind different decisions by the Balanced team, being open about progress/timelines, and giving everyone the ability to be involved in decisions.

—
Reply to this email directly or view it on GitHub.