Process proposal

I've spent a bit of time in a number of groups and think that a lesson learned could be useful.

CoreMob (really Facebook) did research into an area and then moved straight to trying to publish roughly a "specification".

Then people asked "what UC/Requirements are you addressing?" (roughly: "why are you doing this?"), and CoreMob didn't have an answer - because it hadn't published its research. 

For defining an API, these are the things which I think should be answered:

1. [UC] What are the general Use Cases which you're trying to address?
2. [Req] What are the specific technical Requirements to address the UCs?
3. [API] How have others tried to address these UCs and Reqs?
4. [Use] Given others' APIs for these UCs/Reqs, what have people produced which uses this solution?
5. [QQs] What questions have people asked about others' APIs?

* [UC]+[Req] can be published as a single combined Use Case and Requirements document, or as separate documents, but they should be published.
* [API] can be initially a wiki and will probably end up in an informative appendix to a published specification.
* [Use] should be a survey - roughly producing a spreadsheet, preferably with some charts showing popularity/use - preferably highlighting which UCs/Reqs are addressed/how well/how used.
* [QQs] can initially be some sort of wiki/spreadsheet - it should show which are the most common causes of confusion / problems that aren't easily solved for the existing APIs. It doesn't need to be published per se, but being able to reference it informatively from the spec is useful "we tried to avoid (most) these problems when we wrote our specification". Sources for this include sites like "Stack Overflow" (as well as any group's actual FAQ pages).

I think that SysApps (and really every other group) should keep this in mind when it tries to produce any API.

---------------------------------------------------------------------
This transmission (including any attachments) may contain confidential information, privileged material (including material protected by the solicitor-client or other applicable privileges), or constitute non-public information. Any use of this information by anyone other than the intended recipient is prohibited. If you have received this transmission in error, please immediately reply to the sender and delete this information from your system. Use, dissemination, distribution, or reproduction of this transmission by unintended recipients is not authorized and may be unlawful.

Received on Friday, 26 October 2012 18:28:27 UTC