Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Write what counts. Count What Counts.

130 views

Published on

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.

Published in: Technology
  • Be the first to comment

  • Be the first to like this

Write what counts. Count What Counts.

  1. 1. Bob Watson, Ph.D. Senior Technical Writer Amazon Web Services Write what counts. Count what counts. @bobwatsonphd bobw@docsbydesign.com bobwatso@amazon.com API the DocsVirtualConference 2020 May 6, 2020
  2. 2. You’ll learn how to measure documentation success
  3. 3. You won’t learn how to measure everything API the DocsVirtualConference 2020 bobw@docsbydesign.com @bobwatsonphd
  4. 4. This talk is about external performance metrics Performance ForensicInternal External API the DocsVirtualConference 2020 bobw@docsbydesign.com @bobwatsonphd
  5. 5. What is it? Success
  6. 6. Describe the success you want to see bobw@docsbydesign.com @bobwatsonphd API the DocsVirtualConference 2020 bobw@docsbydesign.com @bobwatsonphd
  7. 7. Describe how docs contribute to that success Docs Success bobw@docsbydesign.com @bobwatsonphd API the DocsVirtualConference 2020 bobw@docsbydesign.com @bobwatsonphd
  8. 8. Iterate Measure AnalyzeRevise Describe API the DocsVirtualConference 2020 bobw@docsbydesign.com @bobwatsonphd
  9. 9. Measure AnalyzeRevise Describe Iterate API the DocsVirtualConference 2020 bobw@docsbydesign.com @bobwatsonphd
  10. 10. Goals MetricsTech Describe your goal in a way that is countable and collectable Can you describe it? Can you collect it? Can you count it? API the DocsVirtualConference 2020 bobw@docsbydesign.com @bobwatsonphd
  11. 11. Goals MetricsTech You might not be there, yet API the DocsVirtualConference 2020 bobw@docsbydesign.com @bobwatsonphd
  12. 12. Goals MetricsTech. Iterate on goals, metrics, and tech Can you describe it? Can you count it?Can you collect it? API the DocsVirtualConference 2020 bobw@docsbydesign.com @bobwatsonphd
  13. 13. (there aren’t any) Secrets
  14. 14. Develop your system API the DocsVirtualConference 2020 bobw@docsbydesign.com @bobwatsonphd
  15. 15. API Documentation examples
  16. 16. API docs have many goals API the DocsVirtualConference 2020 bobw@docsbydesign.com @bobwatsonphd
  17. 17. This doc is successful when___________________. Identify each topic’s goal API the DocsVirtualConference 2020 bobw@docsbydesign.com @bobwatsonphd
  18. 18. • This doc is successful when • _(audience)_ __(goal)__. Fill in the blanks API the DocsVirtualConference 2020 bobw@docsbydesign.com @bobwatsonphd
  19. 19. Generalize content goals API the DocsVirtualConference 2020 bobw@docsbydesign.com @bobwatsonphd
  20. 20. Introductory API topics attract Download API the DocsVirtualConference 2020 bobw@docsbydesign.com @bobwatsonphd
  21. 21. •Step 1 •Step 2 •Step 3 Tutorial & Procedural topics demonstrate API the DocsVirtualConference 2020 bobw@docsbydesign.com @bobwatsonphd
  22. 22. Conceptual topics teach API the DocsVirtualConference 2020 bobw@docsbydesign.com @bobwatsonphd
  23. 23. Reference topics answer API the DocsVirtualConference 2020 bobw@docsbydesign.com @bobwatsonphd
  24. 24. Normalize metrics
  25. 25. Observe and iterate API the DocsVirtualConference 2020 bobw@docsbydesign.com @bobwatsonphd
  26. 26. Some assembly required API the DocsVirtualConference 2020 bobw@docsbydesign.com @bobwatsonphd
  27. 27. Describe the success you want to track Collaborate on the descriptions Describe that success in a way that is countable and collectable Know what writing success looks like to help you create and measure it Develop your system for iteration and improvement Create, measure, iterate, and improve! Takeaways API the DocsVirtualConference 2020 bobw@docsbydesign.com @bobwatsonphd
  28. 28. • https://docsbydesign.com/category/technical-writing/audience-market-product/ • https://youtu.be/ax_6cS3JHvY • https://docsbydesign.com/category/technical-writing/reader-goals/ • https://docsbydesign.com/wp- content/uploads/2015/07/Watson_UsingReadersAndOrganizationsGoals.pdf • Brandt, J., Guo, P.J., Lewenstein, J., Dontcheva, M., Klemmer, S.R.: Two studies of opportunistic programming: interleaving web foraging, learning, and writing code. In: Proceedings of the SIGCHI Conference on Human Factors in Computing Systems, ACM, pp. 1589–1598 (2009) • https://docsbydesign.com/category/technical-writing/measuring-value/ • https://docsbydesign.com/wp- content/uploads/2015/01/SIGDOC2014_CogDimForDocEstimate_PosterPaper.pdf References API the DocsVirtualConference 2020 bobw@docsbydesign.com @bobwatsonphd

×