BROADCASTS.com

Tom Johnson Documenting APIs is one of the newer jobs in the technical writing domain. Tom Johnson enjoys the unique challenges of collaborating with and writing for the developers who create and use these Application Programming Interfaces. He also enjoys reflecting on his work and sharing his insights with his fellow technical communicators. We talked about: his evolution from writing to teaching to technical writing to his current focus on API documentation the things he likes about technical writing and how it's such a good fit for him the scope of API documentation and some examples of content provided via APIs the difference between documenting self-contained programs vs. APIs, which don't usually provide a solution on their own how developers access and use APIs how API designers balance the need for flexible use of their API content with the need to not overwhelm users of the API with too much content the differences in assessing and contributing to product design with APIs vs. traditional applications the new ways that usability concerns arise and are addressed in API documentation how tech writers and developers collaborate the differences between writing for technical and non-technical audiences his relationships with field engineers, developer advocates, and other customer-facing teammates how he works with engineering teams the importance of transparency in developer documentation how he manages his workflow when he's supporting multiple teams and products, in particular the importance of being a proactive project manager the unique challenges that solo tech writers face how he feels more engaged in his career when he's writing about it how his academic background in literary nonfiction has had surprising professional benefits how refreshing and fun it is for him to reflect on his professional work and to blog about it Tom's bio Tom Johnson is a professional technical writer in Sunnyvale, California, currently working for Google. When we recorded this interview, he was working for Amazon. He writes a popular blog on technical writing called Idratherbewriting.com, where he explores topics such as API documentation, trends, information design, and more. He also has an extensive online course on API documentation that includes extensive tutorials and other exercises you can follow to build your expertise with APIs, including the OpenAPI specification, Swagger, and more. Connect with Tom on social media Twitter LinkedIn Video Here’s the video version of our conversation: https://youtu.be/hDGIjU5Hzvc Podcast intro transcript Technical writing used to involve explaining stand-alone programs for consumers and other end users of those applications. Nowadays a lot of computing code is released in the form of APIs - Application Programming Interfaces - which are written by developers for other programmers, not for the end user. This creates a whole new class of duties and concerns for tech writers. Tom Johnson has done both of these kinds of technical writing and is really good at explaining how programmers and writers collaborate to document APIs. Interview transcript Larry: Hi, everyone. Welcome to episode number 88 of the Content Strategy Insights podcast. I'm really happy today to have with us Tom Johnson. Tom is a senior technical writer at Amazon. He's a prolific blogger at I'd Rather Be Writing. And he also teaches a course, offers an online course on API documentation. And that's what we're going to talk about today, is APIs. But first, welcome, Tom. And if you'd like to tell the folks anything more about yourself, please. Tom: Thanks, Larry. I'm excited to be on your podcast. I'm based in California in Santa Clara. I've been here about seven years, but I'm a West Coast person. I do love to write. I consider myself foremost kind of a writer who steered his career into technical writing and then into API documentation....