engaging a developer audience: documentation and more
TRANSCRIPT
![Page 1: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/1.jpg)
Engaging a Developer Audience
DeveloperWeek 2015
Documentation and More
![Page 2: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/2.jpg)
Anya StettlerDeveloper Relations
Avalara
anyarms
![Page 3: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/3.jpg)
Why do we need good documentation?
What qualities distinguish “good” documentation?
How can we communicate with developers?
How can we improve existing documentation?
![Page 4: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/4.jpg)
Specifically…
• API Documentation• Web Services type APIs• REST(y) APIs
![Page 5: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/5.jpg)
Do we really need great docs?
YES!
![Page 6: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/6.jpg)
products are complicated
![Page 7: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/7.jpg)
documentation is an afterthought
![Page 8: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/8.jpg)
Good documentation is good
• Decreases barriers to entry• Decreases support costs• Works as a marketing tool
![Page 9: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/9.jpg)
![Page 10: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/10.jpg)
zero to “Hello World”
![Page 11: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/11.jpg)
https://developer.yahoo.com/weather/
![Page 12: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/12.jpg)
https://developer.yahoo.com/yql/console/
![Page 13: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/13.jpg)
Bad documentation makes your users skeptical …
![Page 14: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/14.jpg)
… or sad.
![Page 15: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/15.jpg)
![Page 16: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/16.jpg)
![Page 17: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/17.jpg)
What is good documentation?
A comprehensive,navigableresource thatprovides users theinformation to builda painless,maintainable,successfulintegration to yourservice.
![Page 18: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/18.jpg)
What is good documentation?
A comprehensive,navigableresource thatprovides users theinformation to builda painless,maintainable,successfulintegration to yourservice.
![Page 19: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/19.jpg)
What is good documentation?
A comprehensive,navigableresource thatprovides users theinformation to builda painless,maintainable,successfulintegration to yourservice.
![Page 20: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/20.jpg)
What is good documentation?
A comprehensive,navigableresource thatprovides users theinformation to builda painless,maintainable,successfulintegration to yourservice.
![Page 21: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/21.jpg)
What is good documentation?
A comprehensive,navigableresource thatprovides users theinformation to builda painless,maintainable,successfulintegration to yourservice.
![Page 22: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/22.jpg)
What is good documentation?
A comprehensive,navigableresource thatprovides users theinformation to builda painless,maintainable,successfulintegration to yourservice.
![Page 23: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/23.jpg)
Types of Docs• Technical Reference• Sample Code/Code Snippets• Tutorials (written, video, interactive)
• Application Samples• Q&A Resources
![Page 24: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/24.jpg)
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
![Page 25: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/25.jpg)
https://dev.twitter.com/rest/reference/get/search/tweets
![Page 26: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/26.jpg)
![Page 27: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/27.jpg)
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
![Page 28: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/28.jpg)
https://stripe.com/docs/api
![Page 29: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/29.jpg)
https://www.twilio.com/docs/api/rest/account
![Page 30: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/30.jpg)
![Page 31: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/31.jpg)
http://docs.themoviedb.apiary.io/
![Page 32: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/32.jpg)
https://github.com/tripit/slate
![Page 33: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/33.jpg)
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
![Page 34: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/34.jpg)
http://www.tiobe.com/index.php/content/paperinfo/tpci/index.html
![Page 35: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/35.jpg)
IEEE Spectrum: Top Programming Languages (web)
http://spectrum.ieee.org/static/interactive-the-top-programming-languages#index
![Page 36: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/36.jpg)
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
![Page 37: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/37.jpg)
http://developer.klout.com/io-docs
![Page 38: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/38.jpg)
![Page 39: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/39.jpg)
https://dev.twitter.com/rest/tools/console
![Page 40: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/40.jpg)
![Page 41: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/41.jpg)
![Page 42: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/42.jpg)
![Page 43: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/43.jpg)
https://support.3scale.net/reference/active-docs
![Page 44: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/44.jpg)
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
![Page 45: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/45.jpg)
https://stripe.com/docs/tutorials/charges
![Page 46: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/46.jpg)
https://www.stellar.org/blog/introducing-stellar/
![Page 47: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/47.jpg)
![Page 48: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/48.jpg)
![Page 49: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/49.jpg)
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
![Page 50: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/50.jpg)
https://developers.facebook.com/docs/android/scrumptious/
![Page 51: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/51.jpg)
Q&A resources
• There will still be unanswered questions– Specific use cases– Combinations of resources
• Public answers benefit the community
• Primary values: navigability, simplicity
![Page 52: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/52.jpg)
http://stackoverflow.com/tags
![Page 53: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/53.jpg)
http://stackoverflow.com/help/product-support
![Page 54: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/54.jpg)
https://developer.salesforce.com/forums/
![Page 55: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/55.jpg)
https://twittercommunity.com/
![Page 56: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/56.jpg)
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
![Page 57: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/57.jpg)
Do I really need all those
things?
![Page 58: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/58.jpg)
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
![Page 59: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/59.jpg)
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
![Page 60: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/60.jpg)
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
![Page 61: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/61.jpg)
Information that isn’t accessible isn’t helpful.
![Page 62: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/62.jpg)
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
![Page 63: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/63.jpg)
Pre-existing formats
• RAML• API Blueprint• Swagger• Non-discoverable(e.g. Slate)
![Page 64: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/64.jpg)
investigate……and keep investigating
![Page 65: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/65.jpg)
![Page 66: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/66.jpg)
![Page 67: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/67.jpg)
![Page 68: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/68.jpg)
![Page 69: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/69.jpg)
![Page 70: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/70.jpg)
http://developer.avalara.com
![Page 71: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/71.jpg)
http://developer.avalara.com/api-docs/api-reference/rest-curl/gettax
![Page 72: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/72.jpg)
https://github.com/avadev
![Page 73: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/73.jpg)
![Page 74: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/74.jpg)
So much more!• SDKs• Developer Blog• Posted Release Notes• Formatting tools• XML-based docs• Auto-doc tools• Open source docs
![Page 75: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/75.jpg)
![Page 76: Engaging a Developer Audience: Documentation and More](https://reader037.vdocuments.net/reader037/viewer/2022103117/55b76b56bb61ebc7178b45b7/html5/thumbnails/76.jpg)
Thanks!
Anya StettlerDeveloper RelationsAvalara
slides available athttp://www.slideshare.net/AnyaStettler