Steph Mills - A path through the woods: Defining and documenting top API use cases

API the Docs Virtual Event Series 2020 Recap

This talk was presented at API The Docs Virtual 2020 event series on 6 May. We are glad to present the video recording, slide deck and talk summary below. Enjoy!

Visit our talk recaps ToC page for an overview of all presentations!

Steph Mills

Sr. Staff Technical Writer at Splunk

Steph's presentation (video recording)



Steph's slides



How do I build paths in the docs that readers want to follow?
How to help users find what they need during their journey?
How to make reference documentation more accessible?

User journey creation: explore, map, iterate

  • Analytics
    • Usage statistics for your docs
    • Like a map letting you see the paths readers are currently taking through your docs
    • Tools: Google Analytics, Splunk Zero -- information on behavior patterns

  • Direct customer feedback
    • Comments left on your documentation, find the trends -- information on usability and perceived value
    • Q&A sites, Emails
    • Hearing what readers think of your docs might be the best way figuring out where to place extra guidance in your docs

  • Support Team
    • The support your organization offers to its users is a great resource to look for opportunities on how to better guide your readers
    • Support engineers are fantastic sources of direct customer feedback

  • Sales Team
    • Different perspective on the documentation
    • Questions or comments on the product’s capabilities: is it a new feature or an undocumented combination?

Analyze where you need to add signposts such as tutorials, charts, or procedures.

Three types of API documentation strategies

How to help users to quickly identify which path is best for them?
How to direct and funnel users?

  • Tutorials & Use Cases
    • Specific examples (not general ones)
    • Users can follow along and backtrack towards a specific solution sought by many
    • Not for explaining a concept or loosely related goals

  • Charts & Disambiguation pages
    • Serves as comparison: gives a general idea of what capabilities are available
    • And as splitter: points where to go for more details on specific endpoints

  • Strategic linking
    • Can link to a most common use case on an endpoint from its reference docs
    • Connecting user paths by putting the relevant links to most common entry places
    • Linking from the tutorial to the reference documentation to avoid duplicating content
    • Leave signposts if you move information

Sign up to our Developer Portal Newsletter so that you never miss out on the latest API The Docs recaps and our devportal, API documentation and Developer Experience research publications.