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

1. Documenting APIs
with many pictures of cats

2. Anya Stettler
Developer Relations
Avalara
anyarms

3. Do we really need API Docs?
YES!

6. Good documentation is good
• Decreases barriers to entry
• Decreases support costs
• Works as a marketing tool

8. zero to “Hello World”

9. Bad documentation makes
your users skeptical …

10. … or sad.

13. Types of Docs
• Technical Reference
• Sample Code/Code Snippets
• Tutorials (written, video,
interactive)
• Application Samples
• Q&A Resources

14. 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

15. https://dev.twitter.com/rest/reference/post/statuses/update

16. 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

17. https://stripe.com/docs/api

18. https://www.twilio.com/docs/api/rest/account

20. 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

21. http://www.tiobe.com/index.php/content/paperinfo/tpci/index.html

22. IEEE Spectrum:
Top Programming Languages (web)
http://spectrum.ieee.org/static/interactive-the-top-programming-languages#index

23. 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

24. https://www.stellar.org/blog/introducing-stellar/

27. 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

28. https://developers.facebook.com/docs/android/scrumptious/

29. Q&A resources
• There will still be
unanswered questions
– Specific use cases
– Combinations of
resources
• Public answers
benefit the
community
• Primary values:
navigability,
simplicity

30. So much more!
• SDKs
• Developer Blog
• Posted Release Notes
• Interactive console
• Auto-doc tools

31. Do I really
need all those
things?

32. 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

33. 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

39. http://developer.avalara.com

40. http://developer.avalara.com/api-docs/api-reference/rest-curl/gettax

41. https://github.com/avadev

44. Thanks!
Anya Stettler
Developer Relations
Avalara
anyarms
anya.stettler@avalara.com
slides available at
http://www.slideshare.net/AnyaStettler