Engaging a Developer Audience

DeveloperWeek 2015

Documentation and More

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?

Specifically…

• API Documentation• Web Services type APIs• REST(y) APIs

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

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

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/account

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

https://support.3scale.net/reference/active-docs

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

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.

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

Pre-existing formats

• RAML• API Blueprint• Swagger• Non-discoverable(e.g. Slate)

investigate……and keep investigating

http://developer.avalara.com

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

https://github.com/avadev

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