Podcast: Building Great Documentation -- WAPI FM radio hour
Episode summary
The WAPI.fm site lists the available episodes (three so far):
Here’s the episode with Andrew and me:
Building Great Documentation
This week on WAPI, our CSMs talk with Tom Johnson of idratherbewriting.com 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
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.