Ce diaporama a bien été signalé.
Nous utilisons votre profil LinkedIn et vos données d’activité pour vous proposer des publicités personnalisées et pertinentes. Vous pouvez changer vos préférences de publicités à tout moment.
Documenting APIs 
with many pictures of cats
Anya Stettler 
Developer Relations 
Avalara 
anyarms
Why do we need good documentation? 
What qualities distinguish “good” 
documentation? 
How can we communicate with 
develo...
Do we really need API Docs? 
YES!
Good documentation is good 
• Decreases barriers to entry 
• Decreases support costs 
• Works as a marketing tool
zero to “Hello World”
Bad documentation makes 
your users skeptical …
… or sad.
What is good documentation? 
A comprehensive, 
navigable 
resource that 
provides users the 
information to build 
a painl...
What is good documentation? 
A comprehensive, 
navigable 
resource that 
provides users the 
information to build 
a painl...
What is good documentation? 
A comprehensive, 
navigable 
resource that 
provides users the 
information to build 
a painl...
What is good documentation? 
A comprehensive, 
navigable 
resource that 
provides users the 
information to build 
a painl...
What is good documentation? 
A comprehensive, 
navigable 
resource that 
provides users the 
information to build 
a painl...
What is good documentation? 
A comprehensive, 
navigable 
resource that 
provides users the 
information to build 
a painl...
Types of Docs 
• Technical Reference 
• Sample Code/Code Snippets 
• Tutorials (written, video, 
interactive) 
• Applicati...
Technical Reference 
• Describe everything in 
your API 
– Even things you don’t want 
people to use 
• Structure should f...
https://dev.twitter.com/rest/reference/post/statuses/update
Code Snippets 
• Allow users to learn by 
example 
• Demonstrate a single call 
• Need to be able to 
copy/paste content 
...
https://stripe.com/docs/api
https://www.twilio.com/docs/api/rest/account
There are tools for this 
• Apiary 
• Mashery I/O docs 
• Apigee 
• (and others)
http://docs.themoviedb.apiary.io/
http://developer.klout.com/io-docs
https://apigee.com/console/linkedin
Which Languages? 
• At least three languages 
• At least one raw call/response 
sample 
• Two additional samples implies 
...
http://www.tiobe.com/index.php/content/paperinfo/tpci/index.html
IEEE Spectrum: 
Top Programming Languages (web) 
http://spectrum.ieee.org/static/interactive-the-top-programming-languages...
Tutorials 
• Your product probably 
has some subtlety 
– Authorization 
– Security concerns 
– Expected workflow 
• Can ta...
https://stripe.com/docs/tutorials/charges
https://www.stellar.org/blog/introducing-stellar/
Application Samples 
• More fully-fledged 
“learning by example” 
• Full integration within an 
application context 
• Lar...
https://developers.facebook.com/docs/android/scrumptious/
Q&A resources 
• There will still be 
unanswered questions 
– Specific use cases 
– Combinations of 
resources 
• Public a...
http://stackoverflow.com/tags
https://developer.salesforce.com/forums/
https://twittercommunity.com/
A comprehensive, navigable resource 
that provides users the information 
to build a painless, maintainable, 
successful i...
Do I really 
need all those 
things?
Top 10 APIs 
Tracked 
• Facebook 
• Google Maps 
• Twitter 
• YouTube 
• AccuWeather 
• LinkedIn 
• Amazon Product 
Advert...
What documentation do they 
offer? 
Technical 
Reference 
Code 
Snippets Tutorials 
Interactive 
Console SDK 
Application ...
Comprehensive vs. Concise? 
• Comprehensive 
– Full coverage for technical references 
– Common use cases for tutorials/sa...
Information that isn’t accessible 
isn’t helpful.
http://developer.avalara.com
http://developer.avalara.com/api-docs/api-reference/rest-curl/gettayes
https://github.com/avadev
So much more! 
• SDKs 
• Developer Blog 
• Posted Release Notes 
• Interactive console 
• Auto-doc tools
It’s a good start 
but we’re not done yet.
Thanks! 
Anya Stettler 
Developer Relations 
Avalara 
anyarms 
anya.stettler@avalara.com 
Slides available on 
slideshare
Documenting APIs: Sample Code and More (with many pictures of cats)
Documenting APIs: Sample Code and More (with many pictures of cats)
Documenting APIs: Sample Code and More (with many pictures of cats)
Documenting APIs: Sample Code and More (with many pictures of cats)
Documenting APIs: Sample Code and More (with many pictures of cats)
Documenting APIs: Sample Code and More (with many pictures of cats)
Documenting APIs: Sample Code and More (with many pictures of cats)
Documenting APIs: Sample Code and More (with many pictures of cats)
Documenting APIs: Sample Code and More (with many pictures of cats)
Documenting APIs: Sample Code and More (with many pictures of cats)
Documenting APIs: Sample Code and More (with many pictures of cats)
Documenting APIs: Sample Code and More (with many pictures of cats)
Documenting APIs: Sample Code and More (with many pictures of cats)
Documenting APIs: Sample Code and More (with many pictures of cats)
Documenting APIs: Sample Code and More (with many pictures of cats)
Documenting APIs: Sample Code and More (with many pictures of cats)
Documenting APIs: Sample Code and More (with many pictures of cats)
Documenting APIs: Sample Code and More (with many pictures of cats)
Documenting APIs: Sample Code and More (with many pictures of cats)
Prochain SlideShare
Chargement dans…5
×

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

3 301 vues

Publié le

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

Publié dans : Logiciels
  • Identifiez-vous pour voir les commentaires

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

×