Search results

Podcast: Building Great Documentation -- WAPI FM radio hour

by Tom Johnson on May 7, 2020
categories: technical-writing api-docpodcastingpodcast-guest

I recently participated in an online radio-style chat about documentation with the folks at In an ambitious undertaking, Readme created a 24-hour streaming radio show (called "WAPI FM"') focused on APIs, from March 26-27, 2020. They are publishing some of the recordings week by week. During this hour, Ryan Openshaw and Greg Koberger chatted with Andrew Baker from Twilio and me about a host of documentation topics.

Episode summary

The site lists the available episodes (three so far):

WAPI radio

Here’s the episode with Andrew and me:

Building Great Documentation

This week on WAPI, our CSMs talk with Tom Johnson of and Amazon and Andrew Tork Baker from Twilio about how to build great documentation. Tom shares his findings from a survey on dev doc trends, and Andrew how Twilio been a leader in developer experience for years.

How to listen

You can either listen on WAPI FM or on other sources:

Discussion topics

Here are some topics from the discussion:

  • How we came into the world of API documentation (engineering versus humanities backgrounds)
  • Trends we’re seeing in the developer documentation space
  • Common pitfalls in documenting APIs
  • Treating “code-like-code” and treating “prose-as-prose”
  • Bringing developers into the documentation workflow
  • Best approaches for collaborating with engineers on content development
  • Encouraging a corporate culture that champions documentation
  • Using Markdown as a common format supported by many different tools
  • Prioritizing accuracy of code over accuracy of grammar
  • Spaces where documentation is expanding into, such as video tutorials and developer portals (content strategy for developer docs)
  • Onboarding developers onto a developer experience rather than just giving them a link to documentation
  • The importance of sample apps, and finding the balance around how much tutorial content to create
  • Measuring tech doc usage with product usage and aligning with different product-implementation checkpoints/gates
  • Scaling up demands for live training with hands-on, self-directed approaches
  • Parts of the job that we find the most fulfilling, what we’re most passionate about related to the developer experience
  • How to get into technical writing world, ways to improve documentation

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.