Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Documenting APIs: Sample Code and More (with many pictures of cats)

3,281 views

Published on

A discussion of what makes good API documentation and ways to engage developers through documentation. Presented at API World 2014.

Published in: Software

Documenting APIs: Sample Code and More (with many pictures of cats)

  1. 1. Documenting APIs with many pictures of cats
  2. 2. Anya Stettler Developer Relations Avalara anyarms
  3. 3. Why do we need good documentation? What qualities distinguish “good” documentation? How can we communicate with developers? How can we improve existing documentation?
  4. 4. Do we really need API Docs? YES!
  5. 5. Good documentation is good • Decreases barriers to entry • Decreases support costs • Works as a marketing tool
  6. 6. zero to “Hello World”
  7. 7. Bad documentation makes your users skeptical …
  8. 8. … or sad.
  9. 9. What is good documentation? A comprehensive, navigable resource that provides users the information to build a painless, maintainable, successful integration to your service.
  10. 10. What is good documentation? A comprehensive, navigable resource that provides users the information to build a painless, maintainable, successful integration to your service.
  11. 11. What is good documentation? A comprehensive, navigable resource that provides users the information to build a painless, maintainable, successful integration to your service.
  12. 12. What is good documentation? A comprehensive, navigable resource that provides users the information to build a painless, maintainable, successful integration to your service.
  13. 13. What is good documentation? A comprehensive, navigable resource that provides users the information to build a painless, maintainable, successful integration to your service.
  14. 14. What is good documentation? A comprehensive, navigable resource that provides users the information to build a painless, maintainable, successful integration to your service.
  15. 15. Types of Docs • Technical Reference • Sample Code/Code Snippets • Tutorials (written, video, interactive) • Application Samples • Q&A Resources
  16. 16. Technical Reference • Describe everything in your API – Even things you don’t want people to use • Structure should follow the structure of the API – But can intentionally diverge • Primarily values: comprehensive, navigable • Example: Twitter
  17. 17. https://dev.twitter.com/rest/reference/post/statuses/update
  18. 18. 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
  19. 19. https://stripe.com/docs/api
  20. 20. https://www.twilio.com/docs/api/rest/account
  21. 21. There are tools for this • Apiary • Mashery I/O docs • Apigee • (and others)
  22. 22. http://docs.themoviedb.apiary.io/
  23. 23. http://developer.klout.com/io-docs
  24. 24. https://apigee.com/console/linkedin
  25. 25. 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 they’re maintainable
  26. 26. http://www.tiobe.com/index.php/content/paperinfo/tpci/index.html
  27. 27. IEEE Spectrum: Top Programming Languages (web) http://spectrum.ieee.org/static/interactive-the-top-programming-languages#index
  28. 28. 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
  29. 29. https://stripe.com/docs/tutorials/charges
  30. 30. https://www.stellar.org/blog/introducing-stellar/
  31. 31. 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
  32. 32. https://developers.facebook.com/docs/android/scrumptious/
  33. 33. Q&A resources • There will still be unanswered questions – Specific use cases – Combinations of resources • Public answers benefit the community • Primary values: navigability, simplicity
  34. 34. http://stackoverflow.com/tags
  35. 35. https://developer.salesforce.com/forums/
  36. 36. https://twittercommunity.com/
  37. 37. A comprehensive, navigable resource that provides users the information to build a painless, maintainable, successful integration to your service. • Technical Reference • Sample Code/code snippets • Tutorials (written, video, interactive) • Application Samples • Q&A resources
  38. 38. Do I really need all those things?
  39. 39. Top 10 APIs Tracked • Facebook • Google Maps • Twitter • YouTube • AccuWeather • LinkedIn • Amazon Product Advertising • Pinterest • Flickr • Google Talk Used • Google Maps • Twitter • YouTube • Flickr • Amazon Product Advertising • Facebook • Twilio • Last.fm • eBay • Twilio SMS 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
  40. 40. 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
  41. 41. Comprehensive vs. Concise? • Comprehensive – Full coverage for technical references – Common use cases for tutorials/samples • Length becomes an issue – affects navigation - dilutes understanding - impacts maintenance
  42. 42. Information that isn’t accessible isn’t helpful.
  43. 43. http://developer.avalara.com
  44. 44. http://developer.avalara.com/api-docs/api-reference/rest-curl/gettayes
  45. 45. https://github.com/avadev
  46. 46. So much more! • SDKs • Developer Blog • Posted Release Notes • Interactive console • Auto-doc tools
  47. 47. It’s a good start but we’re not done yet.
  48. 48. Thanks! Anya Stettler Developer Relations Avalara anyarms anya.stettler@avalara.com Slides available on slideshare

×