Documenting APIs

with many pictures of cats

Anya StettlerDeveloper Relations

Avalara

anyarms

Why do we need good documentation?

What qualities distinguish “good” documentation?

How can we communicate with developers?

How can we improve existing documentation?

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,navigableresource thatprovides users theinformation to builda painless,maintainable,successfulintegration to yourservice.

What is good documentation?

A comprehensive,navigableresource thatprovides users theinformation to builda painless,maintainable,successfulintegration to yourservice.

What is good documentation?

A comprehensive,navigableresource thatprovides users theinformation to builda painless,maintainable,successfulintegration to yourservice.

What is good documentation?

A comprehensive,navigableresource thatprovides users theinformation to builda painless,maintainable,successfulintegration to yourservice.

What is good documentation?

A comprehensive,navigableresource thatprovides users theinformation to builda painless,maintainable,successfulintegration to yourservice.

What is good documentation?

A comprehensive,navigableresource thatprovides users theinformation to builda painless,maintainable,successfulintegration to yourservice.

Types of Docs• Technical Reference• Sample Code/Code Snippets• Tutorials (written, video, interactive)

• Application Samples• Q&A Resources

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

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– Must work!

• Primary values: painless, readability, simplicity

• Example: Stripe, Twilio

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 multi-language support

• Popularity• Target audience• The more the merrier

• as long as they’re maintainable

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#index

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

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

• Larger samples

• More like a POC

• Primary values: readability, navigability

• Example: Facebook

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

Q&A resources

• There will still be unanswered questions– Specific use cases– Combinations of resources

• Public answers benefit the community

• Primary values: navigability, simplicity

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 integration to your service. • Technical Reference• Sample Code/code snippets• Tutorials (written, video, interactive)

• Application Samples• Q&A resources

Do I really need all those

things?

Top 10 APIsTracked• 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/23http://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

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 yesAmazon 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

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

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

but we’re not done yet.

It’s a good start

Thanks!

Anya StettlerDeveloper RelationsAvalara

anyarmsanya.stettler@avalara.com

Slides available on slideshare