Episode 2
Tom Johnson
February 23rd, 2022
38 mins 7 secs
Season 1
Your Hosts
Special Guest
About this Episode
Sponsored by
Document Write · EthicalAds · Sourcegraph
Panelists
Portia Burton | Eric Holscher
Guest
Tom Johnson
Show Notes
Hello and welcome to Let’s Talk Docs, the show where we’ll talk about documentation, open source, tech, and the intersection of the three. Today, we’re talking to Tom Johnson, who’s a tech writer and has worked at both startups and big tech for the past 17 years. He has a blog called, I’d Rather be Writing, which he’ll tell us about, as well as an API doc course that provides a lot of free information on how to write API documentation. Tom goes in detail about the checklists he made that make for good API documentation, the research he did, and the feedback he received about them. We’ll find out more about the Pronovix Developer Portal Awards that Tom participated in and what he focused on when evaluating each developer’s portals, how receiving an MFA in non-fiction writing personally helped him, and something he’s currently working on that he’s excited about. Go ahead and download this episode now to learn more!
[00:01:02] Tom explains his API checklists and what prompted him to do it.
[00:04:38] We learn about the Pronovix Developer Portal Awards and the approach that was taken when evaluating these knowledge centers. We also learn what is bad in terms of the developer portal.
[00:07:17] Find out what the characteristics are of good “curb appeal” when it comes to developer documentation.
[00:11:58] Eric wonders how Tom gets the user’s perspective when he’s evaluating the quality and if he had a specific user in mind for the awards.
[00:15:11] Portia wonders the best way to interact with users if you are a small start-up.
[00:20:34] We learn about the feedback Tom got on his API checklist.
[00:25:56] The conversation takes a turn to finding out Tom’s origin story, how he ended up writing about documentation, and keeping a blog since 2006.
[00:29:01] Tom mentioned he received an MFA in non-fiction writing and he tells us how it’s personally helped him shape his writing.
[00:36:50] We end with Tom sharing with us a series he’s currently working on.
Quotes
[00:06:07] “It’s one of those things where you know it when you see it.”
[00:31:53] “There’s always things that are interesting to explore.”
[00:33:28] “Write the Docs is an international community of people who are really passionate about writing and finding each other, and that didn’t exist before the docs so that’s really big and meaningful.”
Links
Measuring documentation quality through user feedback
Five basketball strategies and how they might apply to tech comm
A hypothesis about influence on the web and the workplace
My life story, or reflections on what shaped my life’s career trajectory
Documenting APIs: A guide for technical writers and engineers
Quality checklist for API documentation
Credits
- Executive Produced by Justin Dorfman
- Edited by Paul M. Bahr at Peachtree Sound
- Show notes by DeAnn Bahr at Peachtree Sound
- Cover art by Eriol Fox
