Skip to main content

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

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!

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

 

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.

Sign up

Newsletter

Articles on devportals, DX and API docs, event recaps, webinars, and more. Sign up to be up to date with the latest trends and best practices.

 

Subscribe