documenting apis with cats

Documenting APIs

GlueCon 2015

with 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 great docs?

YES!

products are complicated

documentation is an afterthought

Good documentation is good

• Decreases barriers to entry• Decreases support costs• Works as a marketing tool

When evaluating an API…

http://www.programmableweb.com/news/api-consumers-want-reliability-documentation-and-community/2013/01/07

zero to “Hello World”

https://developer.yahoo.com/weather/

https://developer.yahoo.com/yql/console/

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

• Shortcuts: API design, ‘automatic’ documentation, formatting

https://dev.twitter.com/rest/reference/get/search/tweets

Automatic Documentation

• Less error-prone• Takes less time

… but it’s only part of the story!

• Documentation needs to explain things to people– Different writing skills

• Communication is too important to play second fiddle in comments

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• Code should be simple, readable (not clever)

• Example: Stripe, Twilio

https://stripe.com/docs/api

https://www.twilio.com/docs/api/rest/call

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

https://github.com/tripit/slate

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

Fancy Code Snippetsvia interactive console

• Allows users to play with data

• Real calls to API• User credentials, parameters

• Tools:- Mashery I/O Docs- Apigee- 3scale

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

https://dev.twitter.com/rest/tools/console

http://petstore.swagger.io/

Tutorials

• Your product probably has some subtlety– Authorization– Security concerns– Expected workflow

• Can take many formats– Step-by-step articles– Videos/screencasts– Interactive

• Key Values: successful, painless

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

https://www.stellar.org/developers/

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: Twilio

https://www.twilio.com/docs/howto/walkthrough/appointment-reminders/ruby/rails

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

http://stackoverflow.com/help/product-support

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 APIsArticle• 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/apis (As of 2015-02-09)

Popularity• Facebook• Kayak* • Google Maps• Skype • Waze• Netflix* • Fresh Logic Studios Atlas*

• Yahoo Weather• AirBNB*• Twitter

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

Skype URI yes yes yes no no no yes

Waze yes yes yes no no no yes

Yahoo Weather yes yes yes yes no no yes

* Does provide a JavaScript sample for one resource ** Replaced May 2013, no longer updated

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.

Keep it up to date!

• Inaccurate is as bad as missing

• Only way to make integrations maintainable

Creating Documentation

• Don’t build it from scratch

• Evaluate the best description format for you

• Use existing tools to make your site all fancy

• Continue to evolve

investigate……and keep investigating

http://developer.avalara.com

https://github.com/avadev

http://developer.avalara.com/api-reference

So much more!• SDKs• Developer Blog• Posted Release Notes• Formatting tools• XML-based docs• Auto-doc tools• Open source docs

Thanks!

Anya StettlerDeveloper RelationsAvalara

anyarmsanya.stettler@avalara.com

slides available athttp://www.slideshare.net/AnyaStettler