Bob Watson PhD profile image

Bob Watson, PhD

Amazon Web Services

Write What Counts and Count What Counts


Bob Watson holds a Ph.D. in Human-Centered Design & Engineering from the University of Washington, Seattle and is one of the few people in the world who can say they have a Ph.D in API documentation and design. He is currently applying his engineering, research, and teaching experience as a Senior Technical Writer for Amazon Web Services. His career accomplishments include developing software and documentation for Microsoft, Comcast, and others, and teaching research methods and technical communication to graduate and undergraduate students.

Talk description

Do you meet your customers where they are along their journey with your API? Do you know? This talk shares practical tips on how to meet customers’ goals with your API docs and how to measure how well the docs meet those goals. Spoiler alert: it’s easier than it looks but, one size doesn’t fit all!

The goals of your API’s audience vary throughout the life-cycle of their interaction with your API. In this talk, I discuss the practical aspects of customer goals, how you can meet them with your API documentation, and how to measure how well you meet them as your you, your API, and your customers evolve. I’ll review the key phases of customers’ interactions with your documentation from the readers’ perspective. For each phase, I discuss the customer goals at that phase and the key metrics that track how well you’re meeting them. You’ll learn what to watch, watch out for, and what to ignore (because it will just distract you from your goal of meeting their goals).

This talk is different from many in that it presents the four common categories of API documentation (landing pages, tutorials & procedures, conceptual, and reference topics) as tools to address specific customer needs as they evolve instead of simply a checklist of required content. Initially, customers are looking for a new or an easier way to do something, so your landing pages and “hello world” examples must attract and show them how your product is the one they’re looking for. After that, your customer must successfully apply your product to their problem and your tutorials and conceptual content can help. Finally, your reference topics and community must be ready to help your customers cross the finish line to deployment and release. Along this journey customer needs and goals vary, so must the content and the corresponding measures of success. In the context of goals, the metrics you can (and cannot) use become much clearer and more useful.

After hearing this talk, this will all become much clearer and more useful to you. This talk will benefit most technical writers who have developed or participated in developing a complete set of API documentation and are ready to up their game; however, the concepts are presented so that technical writers who are starting their first API documentation project will also be able to apply the tools and concepts presented.