I'd Rather Be Writing

Follow I'd Rather Be Writing
Share on
Copy link to clipboard

Topics and issues for technical writers. Improve your technical communication role. Empower users with better documentation.

Tom Johnson


    • Mar 7, 2023 LATEST EPISODE
    • infrequent NEW EPISODES
    • 40m AVG DURATION
    • 204 EPISODES


    Search for episodes from I'd Rather Be Writing with a specific topic:

    Latest episodes from I'd Rather Be Writing

    Presentation recording: Specialization myopia syndrome and the content journey

    Play Episode Listen Later Mar 7, 2023 50:52


    This is a recording of a presentation called Specialization myopia syndrome and the content journey, which I gave to a company's private tech comm event. With their permission, I'm posting it here. You can watch the recording via YouTube or listen the audio file as a podcast.

    Podcast: All about Redocly, with founder Adam Altman

    Play Episode Listen Later Feb 26, 2023 36:16


    In this podcast, I chat with Adam Altman all about Redocly, an authoring/publishing tool for creating API documentation. Topics we discuss include why he started Redocly, the approach to API doc tools, what explains the continued popularity of Redocly, the docs-as-code approach to API tooling, and more.

    Podcast about Archbee -- a new documentation tool with a block-based editor, API publishing capability, content re-use, and more

    Play Episode Listen Later Oct 31, 2022 29:09


    Archbee is a relatively new documentation tool that offers a block-based editor, API publishing capability, content re-use, and more. The initial version of Archbee was released in early 2019. Since then, the product has been steadily ramping up in features and growing its customer base. In this podcast, I chat with Claudiu Dascalescu about Archbee, the features driving its adoption, their target audience, and more.

    Keynote presentation to STC India 2022 (Trends to follow or forget)

    Play Episode Listen Later Mar 26, 2022 57:12


    This post is part of a series that explores tech comm trends that I've either followed or forgotten, and why. The overall goal is to better understand the reasons that drive trend adoption or abandonment in my personal career. This post contains a keynote presentation I gave to STC India on March 26, 2022.

    [Podcast] Become a technical writer: conversation with Bobby Kennedy about the technical writing courses he offers

    Play Episode Listen Later Feb 21, 2022 0:30


    I recently chatted with Bobby Kennedy to learn more about the technical writing courses he's offering at becometechnicalwriter.com. In this podcast, he shares a bit about why he started offering technical writing courses, some of the activities and strategies in the courses, and the outcomes so far.

    MEGAComm recording: How to increase awareness of tech comm inside corporate walls

    Play Episode Listen Later Feb 10, 2022 52:55


    I recently gave a presentation called How to increase awareness of tech comm inside corporate walls at the MEGAComm 2022 conference, which is a conference for tech comm professionals in Israel. The recording, slides, and description of my presentation are available below.

    Presentation recording -- 'Best practices in API docs: Product overviews and getting started tutorials'

    Play Episode Listen Later Oct 29, 2021 61:35


    I recently gave an online presentation about product overviews and getting started tutorials in API docs, sponsored by the STC Washington, D.C.-Baltimore Chapter. This post provides a recording of the presentation and related details.

    tcworld China 2021 keynote: 'Tech comm and marketing: How to make your tech comm group more visible to those within your company'

    Play Episode Listen Later Sep 16, 2021 62:30


    I recently gave a keynote presentation at tcworld China 2021 on the topic of tech comm and marketing. This post provides a recording of the presentation, slides, and detailed notes for the presentation.

    Recording of 'Product overviews vs. getting started tutorials: striking a balance between read-first and try-first user behaviors'

    Play Episode Listen Later Aug 7, 2021 49:06


    I recently gave a webinar to tekom Europe about product overviews and getting started tutorials. The recording and slides are below.

    Videocast: Micro content and Flare -- Conversation with Kate Schneider

    Play Episode Listen Later Mar 21, 2021 31:05


    In this videocast, I chat with Kate Schneider about micro content and Flare. Kate shares micro content examples from her current documentation and explains the strategies she considers when creating micro content. She shows specifically how to leverage analytics in determining micro content topics.

    The story behind Document360 -- podcast with founder Saravana Kumar

    Play Episode Listen Later Nov 17, 2020 32:12


    In a previous post, I explored how Document360, a new cloud-based documentation platform, handles API documentation scenarios. This time, I decided to record a podcast with Saravana Kumar, founder of Document360, to get the behind-the-scenes story about how Document360 came about, what's driving their fast pace of development, and their roadmap for the future.

    Playing a product design role as a content designer -- podcast with Jonathon Colman

    Play Episode Listen Later Aug 24, 2020 46:20


    In this podcast, I chat with Jonathon Colman about an innovative work model they implemented at Intercom with content designers. In their experimental model, content designers were allocated to one project only, and they expanded their roles to include not only content design but product design as well. These content/product designers engaged on a deeper level to help products succeed.

    A tip for doc reviews -- bring a list of questions

    Play Episode Listen Later Jul 24, 2020 8:08


    Although doc reviews are a central part of the tech writing process, it's often a challenge to get teams to review docs. One tip is to bring a list of questions to the doc review. This provides more structure and focus to the review meeting.

    Writing productivity tip: Focus sessions

    Play Episode Listen Later Jul 12, 2020 8:08


    I'm trying out a new writing productivity tip that seems to be working fairly well for me: focus sessions. A writing focus session is a one-hour session focused on a writing task. I made a goal last week of doing four writing focus sessions (at work) each day. I figured I should at least be able to devote half of my work day as a professional technical writer doing writing. This technique has boosted my writing productivity recently.

    Developer portal strategies for complex landscapes -- conversation with Kristof van Tomme

    Play Episode Listen Later Jun 24, 2020 52:24


    Recently I chatted with Kristof van Tomme, CEO and co-founder of Pronovix, about a topic that's become increasingly relevant in the past several months: how to deal with complex, rapidly evolving landscapes. Specifically, we focus on developer portal strategies that involve finding a balance between constraints and flexibility. Too many constraints reduces your ability to adapt to uncertain changes that might require innovative, unknown solutions. Too much flexibility might not lead to any coherent, overarching story about how to use your APIs in an integrated way toward a business goal.

    API the Docs recording: How Trends in API Documentation Differ from other Tech Comm Trends

    Play Episode Listen Later Jun 4, 2020 32:02


    I recently presented a session at the API the Docs virtual series on Wednesday, May 27, 2020, as part of the 5th edition. My session covered dev doc trends, and another session covered API design. A recording of my presentation is available below.

    WTD Australia event recording — 'Remote discussion: Techcomm in the times of pandemic'

    Play Episode Listen Later May 31, 2020 70:47


    I recently co-presented in a WTD Australia event titled Techcomm in the times of pandemic on May 28, 2020. The other presenter was professor Kirk St. Amant. A recording is available below.

    Are technical writers increasingly playing non-technical roles? Some thoughts on the evolution of technical writing roles

    Play Episode Listen Later Mar 30, 2020 26:55


    How is the role of the technical writer evolving? It seems we're moving away from writing and more towards other roles, such as reviewer/convener, user champion, editor, publisher, and promoter. However, it's difficult to gauge change, especially across different job categories. In some scenarios, writing might never have been why we were hired.

    Podcast: Users as producers of knowledge — conversation with Nupoor Ranade about how tech writer roles are changing

    Play Episode Listen Later Mar 29, 2020 50:06


    How can users shape and influence the documentation you're producing? In this podcast, I chat with Nupoor Ranade, PhD candidate at North Carolina State University, about how the roles of technical writers are changing. Instead of writers authoring content for passive users, users are actively directing and shaping the knowledge that writers produce. In this podcast, we look at ways docs-as-code workflows are facilitating that shift in roles. This podcast is more of a conversation, where I first ask Nupoor a series of questions, and then she asks me questions. There's also a transcript of the podcast.

    Webinar recording: How Trends in API Documentation Differ from other Tech Comm Trends

    Play Episode Listen Later Mar 12, 2020 59:01


    I recently gave a webinar on trends in developer docs to the STC Washington DC chapter on March 12, 2020. In this presentation, I presented the results and analysis of my Trends in Developer Documentation 2020 survey. A recording and audio file is available below.

    Introduction to API documentation - Recording from Los Angeles API documentation workshop

    Play Episode Listen Later Mar 11, 2020 88:07


    In January I gave an API documentation workshop in Los Angeles, and I recorded the first section of the workshop. This section provides an introduction to APIs, including an overview of APIs, the API doc market, info about API popularity, how to submit requests through Postman, and other trends. The recording is available as both a video/audio or standalone audio.

    Podcast: How Paligo is filling a niche in the CCMS market for complex documentation, with Anders Svensson

    Play Episode Listen Later Mar 9, 2020 51:35


    I recently chatted with Anders Svensson about how Paligo, a cloud-based CCMS, is filling a niche in the CCMS market for complex documentation needs. Complex documentation refers to documentation with multiple product variants, versions, languages, audiences, and more. In these scenarios, content re-use and scalability become more challenging. Paligo is filling a need for documentation teams that have grown beyond their help authoring tools and need the more robust support that a component content management system (CCMS) offers but without the price tag and implementation timeline.

    Podcast with Andrew Davis: Hiring API doc writers -- an inside look at fixing broken processes

    Play Episode Listen Later Feb 23, 2020 55:11


    I recently chatted with Andrew Davis, a recruiter for API documentation positions in the San Francisco Bay area, about why it's so difficult to hire technical writers for developer documentation roles. Andrew has more experience and knowledge with developer doc jobs, companies, and recruiting processes than nearly anyone else in the tech comm industry. He actually helped me find my first dev doc job when I transitioned to California years ago. Andrew's company is called Synergistech Communications. In this interview, Andrew provides an inside look at fixing broken processes around hiring.

    From API docs to developer portals

    Play Episode Listen Later Feb 9, 2020 32:29


    One comment I often hear from API workshop participants and other readers is that they want a more advanced API course. I've been thinking about what that more advanced course would involve, in addition to what might be involved in leveling up at my work, and I've come to a realization that I need to transition more from API documentation to developer portal strategies. Developer portal strategies includes API documentation but also encompasses broader concerns as well, not too different from content strategy.

    Podcast: API Design and Usability with Arnaud Lauret (API Handyman)

    Play Episode Listen Later Dec 7, 2019 54:39


    Arnaud Lauret, also known as the API Handyman, recently published a book called The Design of Web APIs. In this podcast, I chat with Arnaud about his book, specifically exploring best practices for designing web APIs and focusing on the roles technical writers can play.

    Podcast: Dealing with Project Overload -- Strategies to Manage Overflowing Documentation Tasks

    Play Episode Listen Later Oct 2, 2019 20:07


    In this podcast, I talk about how to deal with project overload, specifically covering strategies to manage tasks. Scrum is one framework for dealing with project work by allowing you to limit the work you have before you in a more systematic way. I also explain the importance of focusing on a project to build up flow and momentum, without always context switching.

    Podcast: 10 myths about API documentation

    Play Episode Listen Later Sep 29, 2019 31:53


    In this podcast, I debunk 10 myths about API documentation. For example, some myths are that only engineers can write API docs, or that you have to write API docs by deciphering an engineer's source code. In this podcast, I go through these myths one by one with discussion and analysis.

    Recording of Tech Comm Trends Presentation (STC Puget Sound chapter)

    Play Episode Listen Later Jun 8, 2019 86:50


    I recently gave a presentation on technical communication trends to the STC Puget Sound Chapter in Seattle, Washington, on May 21, 2019. This is one of the better presentations on trends I've given and culminates a lot of research and other iterations on this topic during the past year. You can view a recording of the presentation, check out the slides, grab the audio file, and see other details here.

    Crash course in API documentation -- a one-hour video

    Play Episode Listen Later May 16, 2019 58:04


    If you want a condensed, one-hour version of what I cover in my API documentation workshop, check out this crash-course video.

    Corporate exodus narratives: A close look at the tension between the corporation and academia

    Play Episode Listen Later Mar 1, 2019 27:52


    Corporations often expect tech comm academics to fashion their curriculums to suit corporate needs; in contrast, academic departments want to give students a safe space free of corporate agendas for critical inquiry. Tech comm academics are often caught between these two groups and must satisfy both.

    Recording and slides for my trends presentation at the Symposium for Communicating Complex Information (SCCI)

    Play Episode Listen Later Feb 24, 2019 42:01


    This week I traveled to Louisiana to attend the Symposium for Communicating Complex Information and presented on tech comm trends. You can listen to the recording, view my slides, and read my latest thoughts on trends here.

    How to become a 10X technical writer in the workplace

    Play Episode Listen Later Feb 7, 2019 23:52


    How do you become a 10X technical writer in the workplace (10X means 10 times more efficient and productive than others)? In this post, I raise the question and then offer a few tips I try to follow: (1) Record your meetings with engineers, (2) Respond quickly to emails and messages, (3) Iterate on content with ever-expanding layers of reviewers, (4) Put some work back on those who request it, and (5) Learn to say no so you can focus on fewer projects with deeper engagement.

    How to motivate users to provide feedback: Show that you're listening to their input

    Play Episode Listen Later Feb 1, 2019 9:48


    To encourage users to leave more feedback, add a contact email field on your feedback submission form. When you receive feedback, provide a quick response that shows you're listening and taking action on their input.

    Site analytics from Jan 1 to Dec 31, 2018 -- are more engineers writing docs now?

    Play Episode Listen Later Jan 14, 2019 33:35


    Every year, when I re-examine my site analytics, I take the time to reflect on trends I’m seeing with traffic to my own site. Not necessarily industry trends, just trends about which topics are popular on my site. Based on these trends, I assess and re-evaluate some of my directions. This year, I found that the increase in traffic on my API documentation site (which accounts for 59% of my overall site traffic) suggests that more engineers are writing docs. This confirms my earlier predictions at the beginning of 2018 that specialization will drive more engineers to write API documentation, with technical writers playing more supporting editorial and publishing roles.

    Recording for Menlo Park API documentation workshop now available -- and some thoughts on using cardioid versus omnidirectional microphones for recording

    Play Episode Listen Later Dec 4, 2018 11:05


    The recording for the full-day API workshop that I recently gave in Menlo Park, California, is now available. This recording provides more than 5 hours of instruction about writing API docs -- for free. I also share some thoughts on cardioid versus omnidirectional microphones, and which is better in a workshop setting. The audio narration of this post switches around the microphones so you can hear the difference.

    New post in Simplifying Complexity series -- Principle 11: Be both a generalist and specialist through your technical acuity

    Play Episode Listen Later Nov 30, 2018 62:10


    In my Simplifying Complexity series, I added a new post called, Principle 11: Be both a generalist and specialist through your technical acuity. I also recorded this essay as a narrated podcast.

    How to avoid being a secretary for engineers

    Play Episode Listen Later Nov 19, 2018 27:16


    If we just see our task as documenting solutions that engineers have solved, it removes the creativity and critical thinking dimension from tech comm. The creative dimension in tech comm comes into play as we identify and solve tech comm challenges, such as devising ways to simplify complexity or otherwise improve the user experience.

    I'd Rather Be Writing is now an Alexa Flash Briefing skill

    Play Episode Listen Later Nov 5, 2018 8:48


    Now you can listen to the latest narrated post on I'd Rather Be Writing as an Alexa Flash Briefing skill. This means you can listen to my audio content through your Echo device.

    Upcoming full-day API documentation workshop in Menlo Park

    Play Episode Listen Later Oct 31, 2018 1:08


    I'm giving a full-day API documentation workshop on Nov 8, 2018, in Menlo Park, California, in coordination with Scott Abel (aka, The Content Wrangler). There are still a few open spots left in the workshop.

    Preferring technical acuity over specialized knowledge

    Play Episode Listen Later Oct 24, 2018 13:07


    In the debate between being a specialist or generalist, there's also a third option: developing technical acuity. A person with a high degree of technical acuity has the technical mindset needed to understand and solve problems across a variety of technical domains. Given the ever growing number of technologies, developing technical acuity can be more advantageous, especially in technical writing contexts since technical writers work with a lot of different technologies.

    If writing is no longer a marketable skill, what is?

    Play Episode Listen Later Aug 9, 2018 25:35


    When we try to sell our tech comm skills, promoting our writing skills doesn't seem to impress people anymore, as writing is considered more of a presumed skill everyone has. To give a sense of value, we need to hyphenate our job titles, becoming more of a hybrid professional.

    My conflicted thoughts about the decentralized web (while taking the Census of Technical Communicators survey)

    Play Episode Listen Later Aug 6, 2018 24:44


    Seeing my name in the Census of Technical Communicators survey as a possible source for professional development made me think about the impact of blogs as a learning resource. Advertising encourages bloggers to create rapid-fire, lightweight content in order to increase page views and other attention on the advertised product or service. The proliferation of blog content turns the wheels of social media, creating micro-bursts of attention for companies. The negative impact, however, is that more traditional forms of learning, such as scholarly journal articles and books, take a hit. The web's architecture and monetization model around content is optimized for blog content, so unless other mediums can find a way to become more visible and engaging within the architecture of the web, they will continue their slide into invisibility (at least to mainstream users).

    Articulating stories that influence product adoption (new article in Simplifying Complexity series)

    Play Episode Listen Later Jul 31, 2018 43:19


    I added a new article in my ongoing series about simplifying complexity. The article is called Articulating the invisible stories that influence product adoption or rejection and explores why adoption of our products among users doesn't often live up to our expectations. I argue that we need to articulate the story we're telling about the product as well as the story users tell, and identify whether the two are in alignment. Note that you can both read and listen to this article, since I created an audio recording for it.

    The relationship between academics and practitioners -- Podcast with Kirk St. Amant

    Play Episode Listen Later Jul 11, 2018 56:22


    In this podcast, I chat with Professor Kirk St. Amant about the relationship between practitioners and academics. Kirk recently co-authored an article about research as a unifying focus to bring academics and practitioners together. Using this article as the basis for discussion, we dive into origins of the divide, why both practitioners and academics of the same field need each other, potential solutions, and more.

    Reducing the complexity of technical language (new article in Simplifying Complexity series)

    Play Episode Listen Later Jul 11, 2018 43:29


    I added a new article in my ongoing series about simplifying complexity. The article is called Reducing the complexity of technical language and explores reasons why the language in technical documentation tends become so full of jargon and other unfamiliar terms, and a few solutions for simplifying the language. I emphasize the need to read the competitor's documentation and other articles in the industry to get a sense of the right terms and contexts that users likely expect. I also decided to read the article for those who prefer podcasts.

    language technical reducing simplifying complexity
    Evaluating the user experience of documentation -- Podcast with Bob Watson

    Play Episode Listen Later Jun 18, 2018 58:19


    This week I chatted with Bob Watson, an assistant professor of tech comm at Mercer University, about how to evaluate the user experience of documentation. The idea of doing a podcast came up during a comment thread on a previous post about reconstructing the absent user. We had a long exchange in the comment threads and thought it would be good to have a podcast about the topic.

    Recording of API documentation workshop in Denver

    Play Episode Listen Later Mar 12, 2018 231:12


    I recently gave a half-day API workshop in Denver on March 10, 2018. Topics in the workshop included how to document reference API content (endpoints, parameters, requests, etc.), what non-reference topics (for example, status and error codes, rate limiting, getting started, sample apps) are common, how to create an OpenAPI specification document and Swagger UI output, and more. You can view a recording of the workshop, browse the slides, and listen to the audio here. Because of the length, the content is divided into three parts.

    Recording of STC San Francisco presentation: Beyond mere endpoint reference — the overlooked content in API documentation

    Play Episode Listen Later Mar 8, 2018 59:49


    I recently gave a presentation to the STC San Francisco chapter called "Beyond mere endpoint reference — the overlooked content in API documentation" on February 21, 2018. You can browse the slides and listen to the audio recording here.

    Recording of OpenAPI and Swagger presentation (for STC and WTD San Diego)

    Play Episode Listen Later Feb 14, 2018 61:44


    I recently gave a presentation to the STC San Diego chapter and WTD San Diego group called "Swagger UI and the OpenAPI specification" (February 13, 2018). You can view a recording of the presentation, browse the slides, and listen to the audio here.

    Recording of WTD South Bay presentation: Publishing tools for API documentation

    Play Episode Listen Later Jan 19, 2018 65:21


    I recently gave a presentation called "Publishing tools for API documentation" to the Write the Docs South Bay meetup group on January 18, 2018. You can view a recording of the presentation, browse the slides, and listen to the audio here.

    How to become a voracious reader

    Play Episode Listen Later Dec 1, 2017 6:58


    Voracious reading begins with voracious thinking. Asking questions gives us a purpose and drive for reading.

    Claim I'd Rather Be Writing

    In order to claim this podcast we'll send an email to with a verification link. Simply click the link and you will be able to edit tags, request a refresh, and other features to take control of your podcast page!

    Claim Cancel