Bob Watson, PhD - Write What Counts and Count What Counts

Bob Watson

Senior Technical Writer at Amazon Web Services (AWS)

Bob's presentation (video recording)

Bob's slides

External performance metrics for API documentation.
Map documentation goals with all stakeholders, define success with metrics. Build a collaborative, iterative process.

The goals of your API’s audience vary throughout the life-cycle of their interaction with your API, so must the content and the corresponding measures of success.

• What are the practical aspects of customer goals, how can you meet them with your API documentation?
• How to measure how well you meet customer goals as your API and your customers evolve?
• What are the key phases of customers’ interactions with your documentation from the readers’ perspective?
• What you should monitor, watch out for, and what you should ignore?

API Documentation examples

“Start small, work your way up, identify your goals.”

Find your audience, define the goal of the documentation. Each content type serves different purposes and use cases: identify and serve these specific goals. Generalize content goals into a manageable amount: group the topics by their type.

• Introductory topics
  
  • Landing, Overview, Getting Started, Registration pages
  • Goal: to attract
    
    
• Tutorial and procedural topics
  
  • Step-by-step guides
  • Goal: to demonstrate
    
    
• Conceptual content
  
  • Goal: to teach
    
    
• Reference content
  
  • Goal: to answer

Normalize metrics: baseball or golf scores? Count everything in the same direction for a usable dashboard.
Non-funnel related metrics: will have to assemble tools your own way.

Takeaways

• Define the success you want to track, in each stakeholder's context
• Describe how documentation contributes to that success (e.g., company and/or readers' goals)
• Describe your goal in a way that is countable and collectable
• Measure your success
• Analyze your progress: normalize metrics
• Revise and iterate on goals, metrics, and techs