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

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