Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

The Inverted Funnel of API Documentation

11 views

Published on

Your customers’ success depends not just o running Hello World, but using your API in a complete app to accomplish a business goal. Getting started is definitely important, but it’s just the first step towards the customers’ ultimate goal: getting finished! Let me help you help them finish!

Published in: Technology
  • Be the first to comment

  • Be the first to like this

The Inverted Funnel of API Documentation

  1. 1. @bobwatsonphd docsbydesign.com 8 April 2019 Bob Watson, Ph.D. Assistant Professor, Mercer University The inverted funnel of API documentation Photos from a customer’s journey
  2. 2. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Customer success == API success We’re here to create successful customer journeys
  3. 3. My recent customer journey piClinic Console
  4. 4. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 That’s my latest journey • Each customer journey is different • We’re here to help it be successful!
  5. 5. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 API Docs help your customers navigate their journey
  6. 6. Funnels and pyramids
  7. 7. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Conversion funnels attract prospects Awareness Interest Desire Action Goal: to perform action
  8. 8. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Conversion funnels attract prospects Awareness Interest Desire Action Goal: to perform action Success: Action
  9. 9. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Documentation pyramids Help guide customers Landing Page Hello World Tutorial Reference Goal: customer success with your API
  10. 10. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Documentation pyramids Help guide customers Landing Page Hello World Tutorial Reference Goal: customer success with your API Success: ????
  11. 11. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Customer journeys diverge after passing through the conversion funnel
  12. 12. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Customer journeys diverge after passing through the conversion funnel • Funnel success occurs in one place: conversion. • Customer success occurs in many places.
  13. 13. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Your documentation pyramid needs a solid base Landing Page Hello World Tutorial Reference Quality reference topics carry your customers through the last mile of development
  14. 14. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019
  15. 15. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Reference topics The unsung heroes of API documentation
  16. 16. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Reference topics are valued most Landing Hello World Tutorial Reference Customer: Low value High value (Measured in time) • Minute(s) • An hour or so • A couple of hours • Their product’s future
  17. 17. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Ref. topics are where developers spent the most time in docs Meng, Michael, Stephanie Steinhardt, and Andreas Schubert. 2019. How Developers Use API Documentation: An Observation Study. Communication Design Quarterly. http://sigdoc.acm.org/wp-content/uploads/2019/01/CDQ18002_Meng_Steinhardt_Schubert.pdf
  18. 18. Ref. topics are where developers spent the most time in docs Where devs spent their time 49% 51% Docs Coding Content type % of time API Ref 37.5% Recipes 30.6% Concepts 16.2% Samples 11.6% Welcome Page 2.7% Integrations 1.4% Meng, Michael, Stephanie Steinhardt, and Andreas Schubert. 2019. How Developers Use API Documentation: An Observation Study. Communication Design Quarterly. http://sigdoc.acm.org/wp-content/uploads/2019/01/CDQ18002_Meng_Steinhardt_Schubert.pdf
  19. 19. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Reference topics make your customers smarter Brandt, Joel, Philip J Guo, Joel Lewenstein, Mira Dontcheva, and Scott R Klemmer. 2009. Two Studies of Opportunistic Programming: Interleaving Web Foraging, Learning, and Writing Code. In Proceedings of the SIGCHI Conference on Human Factors in Computing Systems. Pp. 1589–1598. ACM.
  20. 20. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Reference topics make your customers smarter • [One developer said] “that he never bothered to learn [an API] because he ‘knew it would always be there [in the reference documentation].’” Brandt, Joel, Philip J Guo, Joel Lewenstein, Mira Dontcheva, and Scott R Klemmer. 2009. Two Studies of Opportunistic Programming: Interleaving Web Foraging, Learning, and Writing Code. In Proceedings of the SIGCHI Conference on Human Factors in Computing Systems. Pp. 1589–1598. ACM.
  21. 21. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Reference topics make your customers smarter • [The researchers] “believe that in this way, programmers can effectively distribute their cognition, allowing them to devote more mental energy to higher-level tasks.” Brandt, Joel, Philip J Guo, Joel Lewenstein, Mira Dontcheva, and Scott R Klemmer. 2009. Two Studies of Opportunistic Programming: Interleaving Web Foraging, Learning, and Writing Code. In Proceedings of the SIGCHI Conference on Human Factors in Computing Systems. Pp. 1589–1598. ACM.
  22. 22. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Reference topics Fill the gaps in the customer’s journey
  23. 23. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Reference topics Carry the customer across the finish line
  24. 24. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Your customers might be different
  25. 25. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Your customers might be different
  26. 26. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Your customers might be different Find out!
  27. 27. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Your reference topics show customers how important their success with your API is to you!
  28. 28. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Your reference topics show customers how important their success with your API is to you!
  29. 29. Take this with you • Know your customers’ journeys • Be where developers need you • Automate as much as possible • Track the analytics that matter
  30. 30. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Your customers travel many paths • Know: – The key problems that your API solves – How your customers interact with your docs – How your customers write code
  31. 31. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Your customers might be different
  32. 32. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Learn where your customers need documentation in their journey • Many sites ask, “Did this help?” • What if you asked, “Are you:” – Considering this API? – Starting a project? – Finishing a project?
  33. 33. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Be where your customers will need you Be ready with what they will need
  34. 34. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Automate as much as possible • Make your authoring tools work for you • Work with your developers – Integrate documentation content & code – Integrate documentation tools & code • But, don’t abandon the human touch…
  35. 35. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Developers are human, too! Write reference topics for people • Reference topics handle many use cases • Less is NOT more with reference topics • Err on the side of more, not less content
  36. 36. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Count what counts • Sign ups and Hello Worlds show who’s been converted • API usage (API keys, API calls, etc.) shows who’s been successful
  37. 37. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Metrics: one size doesn’t fit all • Monitor individual page performance to find problems • Aggregate reference topic analytics to evaluate use and value – Think of ref. content as a multi-page topic
  38. 38. Take this with you • Know your customers’ journeys • Be where developers need you • Automate as much as possible • Track the analytics that matter
  39. 39. Photos from a customer’s journey API the Docs, Chicago 8 April 2019 Bob Watson, Ph.D. Assistant Professor, Mercer University @bobwatsonphd docsbydesign.com

×