1. Documenting APIs with many pictures of cats

2. Anya Stettler Developer Relations Avalara anyarms 3. Do we really need API Docs? YES! 4. Good documentation is good Decreases barriers to entry Decreases support costs Works as a marketing tool 5. zero to Hello World 6. Bad documentation makes your users skeptical 7. or sad. 8. Types of Docs Technical Reference Sample Code/Code Snippets Tutorials (written, video, interactive) Application Samples Q&A Resources 9. Technical Reference Describe everything in your API Even things you dont want people to use Structure should follow the structure of the API But can intentionally diverge Primarily values: comprehensive, navigable Example: Twitter 10. https://dev.twitter.com/rest/reference/post/statuses/update 11. Code Snippets Allow users to learn by example Demonstrate a single call Need to be able to copy/paste content Must work! Primary values: painless, readability, simplicity Example: Stripe, Twilio 12. https://stripe.com/docs/api 13. https://www.twilio.com/docs/api/rest/account 14. Which Languages? At least three languages At least one raw call/response sample Two additional samples implies multi-language support Popularity Target audience The more the merrier as long as theyre maintainable 15. http://www.tiobe.com/index.php/content/paperinfo/tpci/index.html 16. IEEE Spectrum: Top Programming Languages (web) http://spectrum.ieee.org/static/interactive-the-top-programming-languages#index 17. Tutorials Your product probably has some subtlety Authorization Security concerns Expected workflow Can take many formats Step-by-step articles Videos/screencasts Interactive consoles Key Values: successful, painless 18. https://www.stellar.org/blog/introducing-stellar/ 19. Application Samples More fully-fledged learning by example Full integration within an application context Larger samples More like a POC Primary values: readability, navigability Example: Facebook 20. https://developers.facebook.com/docs/android/scrumptious/ 21. Q&A resources There will still be unanswered questions Specific use cases Combinations of resources Public answers benefit the community Primary values: navigability, simplicity 22. So much more! SDKs Developer Blog Posted Release Notes Interactive console Auto-doc tools 23. Do I really need all those things? 24. Top 10 APIs Tracked Facebook Google Maps Twitter YouTube AccuWeather LinkedIn Amazon Product Advertising Pinterest Flickr Google Talk http://www.programmableweb.com/news/most-popular-apis-least-one-will-surprise-you/2014/01/23 http://www.programmableweb.com/category/all/apis?order=field_popularity *As of 2014-09-13 Used Google Maps Twitter YouTube Flickr Amazon Product Advertising Facebook Twilio Last.fm eBay Twilio SMS 25. What documentation do they offer? Technical Reference Code Snippets Tutorials Interactive Console SDK Application Samples Q&A Facebook yes yes yes yes yes yes yes Google Maps yes yes yes no yes no stack overflow Twitter yes JSON only yes yes some no yes YouTube yes yes yes yes yes no stack overflow AccuWeather yes no* yes no no no no LinkedIn yes yes yes yes 3rd party no yes Amazon Product Advertising yes 3rd party yes no 3rd party 3rd party yes Pinterest yes no yes no yes no no Flickr yes 3rd party yes yes 3rd party no yes Google Talk** yes yes yes no yes no yes Twilio yes yes yes no yes yes yes Last.fm yes no yes no 3rd party no yes eBay yes yes yes no*** yes yes yes Twilio SMS**** yes yes yes no no no yes * Does provide a JavaScript sample for one resource ** Replaced May 2013, no longer updated *** Has request validator tool **** Deprecated 26. http://developer.avalara.com 27. http://developer.avalara.com/api-docs/api-reference/rest-curl/gettax 28. https://github.com/avadev 29. Thanks! Anya Stettler Developer Relations Avalara anyarms anya.stettler@avalara.com slides available at http://www.slideshare.net/AnyaStettler