| Authors: | Adam DuVander |
|---|---|
| Time: | 16:40 |
| Session: | http://docs.writethedocs.org/en/2013/conference/talks.html#adam-duvander |
| Link: |
Lots of APIs being written, explosive growth in the ProgrammableWeb directory, and developers value documentation, and more specifically accurate, timely, transparent documentation. In 2011 a developer survey called out Facebook as the company with the worst API. (They’ve since gotten better). Most companies have an entire team devoted to marketing, and only one person (if you’re lucky) to write developer documentation. So what can we learn from marketing about making APIs appealing by way of the documentation?
So what does your documentation need?
Developers can find the portal for the documentation. This seems like a low bar, but it’s probably not met by lots of those API providers. Clarity also means providing a place where developers can see an overview of the API. Client libraries, sample code, and example apps in the languages developers are using are a way providers can help increase clarity. Finally, using standard authentication methods (OAuth, etc) provide clarity out of the box for developers: it’s one less thing for them to learn.
Developers want to be able to easily understand if there’s a fee to use the service, and related to that is whether or not a rate limit applies. A rate limit is a cost, it’s just charged in developer time. A hidden cost is often Terms of Service, so making that visible and easy to understand is a way to make your API more appealing.
Developers need a way to ask a question and get an answer about using your API. Facebook did this after being named “worst”: they went to StackOverflow, where they knew developers already were, and started answering questions there. YouTube and others shine a spotlight on third party developers, giving them a way to get more exposure within the community. Another way to give exposure to developers is through an app directory. Yellow Pages of Canada does a great job of this. Putting a face to your company’s API efforts – either through documentation or through some other tool – helps developers feel like they’re engaging with other people, not just a company.