documenting apis with cats; gluecon 2015
TRANSCRIPT
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
slides available athttp://www.slideshare.net/AnyaStettler