Episode 2: Tom Johnson

Sponsored by
Document Write · EthicalAds · Sourcegraph

Portia Burton | Eric Holscher

Tom Johnson

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.

[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.”

SustainOSS

SustainOSS Twitter

SustainOSS Discourse

Portia Burton Twitter

Eric Holscher Twitter

Tom Johnson Twitter

Tom Johnson LinkedIn

I’d Rather Be Writing blog

Measuring documentation quality through user feedback

Pronovix Developer Awards

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

• 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

Special Guest: Tom Johnson.

Sponsored By:

• Sourcegraph: Create living documentation that interacts directly with your code.
• DocumentWrite: Sometimes the tech doesn't speak for itself, and that's why you need stellar documentation.