The document discusses what constitutes good API documentation and provides examples. It argues that good documentation includes technical references, code snippets, tutorials, application samples, and Q&A resources. It also notes that top APIs offer many of these elements, and that while comprehensive documentation is ideal, it also needs to be concise and accessible.

1. Documenting APIs
with many pictures of cats

2. Anya Stettler
Developer Relations
Avalara
anyarms

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. 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. What is good documentation?
A comprehensive,
navigable
resource that
provides users the
information to build
a painless,
maintainable,
successful
integration to your
service.

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. What is good documentation?
A comprehensive,
navigable
resource that
provides users the
information to build
a painless,
maintainable,
successful
integration to your
service.

16. What is good documentation?
A comprehensive,
navigable
resource that
provides users the
information to build
a painless,
maintainable,
successful
integration to your
service.

17. What is good documentation?
A comprehensive,
navigable
resource that
provides users the
information to build
a painless,
maintainable,
successful
integration to your
service.

18. What is good documentation?
A comprehensive,
navigable
resource that
provides users the
information to build
a painless,
maintainable,
successful
integration to your
service.

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

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

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

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

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

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

29. There are tools for this
• Apiary
• Mashery I/O docs
• Apigee
• (and others)

30. http://docs.themoviedb.apiary.io/

31. http://developer.klout.com/io-docs

33. https://apigee.com/console/linkedin

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

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

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

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

40. https://stripe.com/docs/tutorials/charges

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

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

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

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

47. http://stackoverflow.com/tags

48. https://developer.salesforce.com/forums/

49. https://twittercommunity.com/

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

51. Do I really
need all those
things?

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

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

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

55. Information that isn’t accessible
isn’t helpful.

61. http://developer.avalara.com

62. http://developer.avalara.com/api-docs/api-reference/rest-curl/gettayes

63. https://github.com/avadev

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

66. It’s a good start
but we’re not done yet.

67. Thanks!
Anya Stettler
Developer Relations
Avalara
anyarms
anya.stettler@avalara.com
Slides available on
slideshare