I think most SDKs spawn because of the well-intentioned idea that a piece of software should do everything it can for everybody. A lot of good ideas start this way. But you know about the road to hell, right?
You've created a product and it's pretty cool. The devs who worked on it used sound software engineering principles when they designed a robust, extensible architecture, pretty much. I say pretty much because they were pressed for time and cut some corners in some places in order to meet some deadline. From there, the germ to create an SDK is born.
But that's not a product.
You run some automated tool to extract comments from the code and it turns out those comments are pretty good. You throw it up on a Web site and people start downloading it.
You start getting a lot of questions on the SDK and you publish some papers up on the Web site. A couple of the devs start writing stuff in their blogs. They get awards for being “responsive.” Some SDK user writes a useful application that mines one of the gaps created when the aforementioned deadline pressure meant cutting a feature.
A whole lot of downloaders complain about the SDK and the especially the docs, which they see as two different things. And a couple of PMs and Lead Writers are called in to put some lipstick on a pig – an expression we use in the States.
What didn't happen that should happen? Products generally don’t get the green light simply because we have the means to create them. Usually, a more robust justification is required. But SDKs don't get this treatment because, as one of my bosses used to say, they are targets of opportunity.
I think that we need to get our heads around the idea that SDKs are products and users of SDKs are consumers.
Having said that, I think SDKs would be more successful if the same rigor were applied to them as is applied to any other product. I'm not sure what I mean by successful here, but it isn't simply the number of downloads.
To produce a successful SDK, you also need to think about these tasks.
This takes time and costs money. Being good at this type of planning (by doing it over and over again) eventually would make it less of a hassle.
If you want to measure improvement, you'll have to build that into the planning, too. I don't think that's crazy talk.
Minor correction - I managed to remove the html formatting to Steven Clarke's blog so I took the opportunity to fix the spelling of his name as well.
How big does an SDK have to before it needs more than just comments created by the developers who have written it?
I think the answer to that question is that depends. Yes, a cop out.
A lot depends on how well the API was designed. Can the design patterns be understood in a very easy way? Are there lots of common get and set properties for example.
In general, you have to know the audience. For me that seems to boil down to two things: what is the user trying to do, and what context are they in?
A lot of contexts have a lot of built-in knowledge. For example, a carpenter has to put in a door. Is it new construction, old construction, just the door, pre-hung door? One look at the job site and he has a pretty good idea of what tools he'll need. Is the API like that?
If you can answer those questions then you can move onto how many people will actually use this API? Twenty? 2,000?
These are all fairly basic questions, I admit. One might even call it market segmentation but that betrays an underlying business analysis and who'd want to do that?