The Inverted Funnel of API Documentation
0 likes150 views
The document discusses the importance of effective API documentation in guiding customer journeys and achieving customer success. It emphasizes the role of reference topics in providing critical support during the coding process, suggesting that comprehensive documentation helps developers navigate their projects more effectively. Key takeaways include understanding customer needs, automating documentation processes, and tracking relevant analytics to improve user experiences.
![@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.](https://image.slidesharecdn.com/bobwatsontheinvertedfunnelofapidocumentation-191113085840/85/The-Inverted-Funnel-of-API-Documentation-22-320.jpg)
![@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.](https://image.slidesharecdn.com/bobwatsontheinvertedfunnelofapidocumentation-191113085840/85/The-Inverted-Funnel-of-API-Documentation-23-320.jpg)
The Inverted Funnel of API Documentation
- 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. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Customer success == API success We’re here to create successful customer journeys
- 3. My recent customer journey piClinic Console
- 6. @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!
- 7. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 API Docs help your customers navigate their journey
- 9. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Conversion funnels attract prospects Awareness Interest Desire Action Goal: to perform action
- 10. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Conversion funnels attract prospects Awareness Interest Desire Action Goal: to perform action Success: Action
- 11. @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
- 12. @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: ????
- 13. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Customer journeys diverge after passing through the conversion funnel
- 14. @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.
- 15. @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
- 16. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019
- 17. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Reference topics The unsung heroes of API documentation
- 18. @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
- 19. @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
- 20. 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
- 21. @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.
- 22. @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.
- 23. @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.
- 24. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Reference topics Fill the gaps in the customer’s journey
- 25. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Reference topics Carry the customer across the finish line
- 26. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Your customers might be different
- 27. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Your customers might be different
- 28. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Your customers might be different Find out!
- 29. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Your reference topics show customers how important their success with your API is to you!
- 30. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Your reference topics show customers how important their success with your API is to you!
- 31. Take this with you • Know your customers’ journeys • Be where developers need you • Automate as much as possible • Track the analytics that matter
- 32. @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
- 33. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Your customers might be different
- 34. @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?
- 35. @bobwatsonphd docsbydesign.com API the Docs 8 April 2019 Be where your customers will need you Be ready with what they will need
- 36. @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…
- 37. @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
- 38. @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
- 39. @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
- 40. Take this with you • Know your customers’ journeys • Be where developers need you • Automate as much as possible • Track the analytics that matter
- 43. Photos from a customer’s journey API the Docs, Chicago 8 April 2019 Bob Watson, Ph.D. Assistant Professor, Mercer University @bobwatsonphd docsbydesign.com