"Building Great Documentation" -- WAPI FM radio hour
I recently participated in an online radio-style chat about documentation with the folks at Readme.com. 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 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
