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

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.
@bobwatsonphd docsbydesign.com API the Docs 8 April 2019
API Docs help your customers
navigate their journey

6.
Funnels and pyramids

7.
@bobwatsonphd docsbydesign.com API the Docs 8 April 2019
Conversion funnels attract
prospects
Awareness
Interest
Desire
Action
Goal:
to perform action

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.
@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.
@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.
@bobwatsonphd docsbydesign.com API the Docs 8 April 2019
Customer journeys diverge
after passing through the
conversion funnel

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.
@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.
@bobwatsonphd docsbydesign.com API the Docs 8 April 2019

15.
@bobwatsonphd docsbydesign.com API the Docs 8 April 2019
Reference topics
The unsung heroes of API
documentation

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.
@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.
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.
@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.
@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.
@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.
@bobwatsonphd docsbydesign.com API the Docs 8 April 2019
Reference topics
Fill the gaps in
the customer’s journey

23.
@bobwatsonphd docsbydesign.com API the Docs 8 April 2019
Reference topics
Carry the customer
across the finish line

24.
@bobwatsonphd docsbydesign.com API the Docs 8 April 2019
Your customers might be different

25.
@bobwatsonphd docsbydesign.com API the Docs 8 April 2019
Your customers might be different

26.
@bobwatsonphd docsbydesign.com API the Docs 8 April 2019
Your customers might be different
Find out!

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.
@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.
Take this with you
• Know your customers’ journeys
• Be where developers need you
• Automate as much as possible
• Track the analytics that matter

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.
@bobwatsonphd docsbydesign.com API the Docs 8 April 2019
Your customers might be different

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.
@bobwatsonphd docsbydesign.com API the Docs 8 April 2019
Be where your
customers will need you
Be ready with what they will need

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.
@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.
@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.
@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.
Take this with you
• Know your customers’ journeys
• Be where developers need you
• Automate as much as possible
• Track the analytics that matter

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