I’m at Write the Docs today in Portland and will be posting notes from sessions throughout the day. These are all posted right after a talk finishes so they’re rough around the edges.
There are close to 9,000 APIs in the ProgrammableWeb directory. Just a while ago this was only a couple thousand. Even companies like Sears, USA Today and others have APIs.
Adam’s most popular tweet from last year was, “All your API documentation should get the same treatment and design as your marketing materials.” That was a quote from John Sheehan.
Adam’s talk was about the Three Cs: clarity, cost, and community.
By clarity of API docs Adam means that developers can actually find their way to the documentation portal. Not all companies have their API docs even remotely accessible. Clarity also means having a complete API reference available in a form that lets developers explore. A clear API also requires sample code. It’s best when it’s in a couple popular languages and can be plugged right in to a project. Decreasing the time to “Hello world” is key.
The cost of an API is also relevant. Developers need to know how much (if any) it costs to use a service and its API. Rate limits are another type of cost that needs to be clearly communicated. Google does this very well with their developer console. You can see usage and request higher limits right inline. Developers also need to find any API-specific terms of service.
For the community of an API Adam talked about needing a place where developers can discuss the API. A forum is a good start but a strong presence where your developers already are (e.g. StackOverflow) is better. Highlighting current work based on the API and focusing on changes coming to that API is another great way to build community. You also have to put a face to your API. Developers need to know who within the company they are or should be talking to.