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!

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

8. Funnels and pyramids

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