In this episode, I’m talking with Lorna Mitchell, a technology leader, published author, tech blogger, and developer experience expert who is passionate about APIs and developer tools. We talk about why developers writing docs is good for both your devs and your docs, the best ways to build successful collaboration with developers, and more!

Lorna and I discuss her background as a developer who started doing documentation for her own resources and gradually moved into developer relations, developer advocacy, and developer experience. We chat about the wide range of writing she’s tackled–including books, readmes, and her blog–and why developers need to write to improve their skills.

We also discuss strategies tech writers can use to facilitate good collaboration with developers, including treating their role more as editors rather than writers; having a clearly-defined process with discrete, well-scoped requests for contributions; creating content type templates to streamline contributions; and having a second, shorter style guide for developers.

About Lorna Mitchell:

Lorna is based in Yorkshire, UK; she is a technology leader and developer experience expert who is passionate about APIs and developer tools. She is also a published author and regular blogger, sharing her insights on a variety of tech-related topics. Lorna serves on the OpenUK board, is on the Technical Steering Committee for OpenAPI specification, and maintains open source projects.

Resources discussed in this episode:

• Lorna’s developer style guide
• Diátaxis for content types
• Write the Docs’ Docs as Code resources
• Tanya Reilly’s Being Glue

—

Contact The Not-Boring Tech Writer team:

We love hearing your ideas for episode topics, guests, or general feedback:

• [email protected]
• Bluesky
  
  

Contact Kate Mueller: 

• knowledgewithsass.com
• LinkedIn
  
  

Contact Lorna Mitchell: 

• Lorna's website
• Linkedin
  
  

Contact KnowledgeOwl:

• KnowledgeOwl.com
  
  

—

Transcript:

Kate Mueller: [00:00:01] Welcome to the Not-Boring Tech Writer, a podcast sponsored by KnowledgeOwl. Together, we explore topics and hear from other writers to help inspire us, deepen our skills and foster our distinctly not boring tech writing community. Hi, I'm Kate Mueller. In today's episode, I talk with Lorna Mitchell. Lorna is a technology leader, published author, tech blogger, and developer experience expert who is passionate about APIs and developer tools. We talk about why developers writing docs is good for both your devs and your docs, and the best ways to build successful collaboration with developers. Welcome everyone! My guest today is a woman who I first discovered through a 'write the docs' talk, who made open API and API documentation actually makes sense and seem like a reasonable form of documentation. And as somebody with no background in API stuff, I figured, you know, if I need to interview somebody who qualifies as not boring, anyone who can make API docs feel not boring feels like someone I should have on the show. So I'm very delighted to welcome Lorna Mitchell to the show today. Hi, Lorna. Welcome.

Lorna Mitchell: [00:00:54] Hi Kate! That is a great intro, thank you so much for having me.

Kate Mueller: [00:00:57] You're welcome. I'm sure you never thought you'd be starting off thinking, wow, what a compliment to be called 'not boring'. But here we are, welcome to the pod. For our listeners, I came from the writing world and accidentally ended up in tech and have ended up writing a fair amount of software and product documentation and a variety of other things. But for me, that was always like an accident. I just sort of ended up here and it's worked. My sense is that you've had the opposite experience, where you started more on the tech side and have accidentally ended up writing some documentation sometimes. Is that true?

Lorna Mitchell: [00:01:35] I think that's a really good reflection. I've always liked words, but I have worked my entire career in software engineering of one kind or another. Along the way, it always seems to be, I've been in charge of multiple docs platforms, and there's a thousand posts on my blog, I wrote some books. This technology thing is amazing, it's easy when you know how and I just can't stop telling people how.

Kate Mueller: [00:02:00] It's a good problem to have. One of the things I've learned is, if you are really excited about the thing you're talking about, people will show up and listen to you. I don't understand how this happens. I've done these half hour sessions at KnowledgeOwl, walking people through new features or whatever. People will be like, I love listening to you talk. I'm like, why? Why do you love this? I mean, it's great, I'm happy you showed up. Here I thought I was just talking into the void, and here we are. Can you talk a little bit about your technical background then since it's, I'd imagine, a little different from a lot of our user's?

Lorna Mitchell: [00:02:43] Yeah, definitely. Actually, confession time, my degree is in electronic engineering, so I'm actually not at all qualified to do what I do. But along the way, we did a bit of software. This is back in the day, obviously I have been doing this for a long time. Maybe you can't tell on a podcast. Anyway, I have been doing this quite a long time. My first job was in software. I wrote games initially, which was a lot less fun than it sounds. It's not the most humane end of the industry, and I have worked in a bunch of other different technical disciplines. I've mostly been in open source, mostly as a back end developer. I also have some accessibility needs. I acquired an arm injury, it's just a horrible tendonitis, in a workplace quite a long time ago. Although my background is in PHP and web development, I became an API specialist because I can't work the front end dev tools. Those all require a mouse and I am keyboard only and I have been for a really large number of years. I'm API and data specialist kind of by necessity, but also this stuff is amazing. I've worked a lot on making computers talk to each other. The humans should not have to take the information and put it in again somewhere else. This exists in the world in digital format, make it happen. In the time that I've been doing this, we've gone from overnight batch jobs to real time streaming data integrations. I have worked on all of that and everything in between.

Kate Mueller: [00:04:22] Wow, that is quite the career and personal life arc. This makes me feel so much more normal because mine has also been equally, how did I get there from here? Actually, it made total sense at the time, but here we are.

Lorna Mitchell: [00:04:38] If I'd ever had a life plan, none of this would have happened. From each place, you just have to take one more step forward. The overall map looks a little bit winding, but I think everything is part of the picture.

Kate Mueller: [00:04:52]...

Meet our new host Kate Mueller and get the inside scoop on how The Not-Boring Tech Writer (TNBTW) will work moving forward.

Kate Mueller is the Documentation Goddess of KnowledgeOwl, a seasoned technical writer and owner of knowledgewithsass, a knowledge management coaching service. She’s written and maintained documentation for companies in broadcasting, financial services, IT, and software for 15+ years. She’ll be hosting TNBTW moving forward.

In this episode, Kate discusses her vision for TNBTW: a podcast dedicated to everyone who is writing technical documentation, including those who may not feel comfortable calling themselves tech writers. Whether you create product documentation, support documentation, READMEs, or any other technical content—and whether you deal with imposter syndrome, lack formal training, or find yourself somewhere in the gray area between technical communications and general writing—the TNBTW reboot might be your new favorite podcast. Kate talks about her own imposter syndrome using the tech writer label and recounts her tech writer villain origin story.

We plan to release two episodes per month: one episode will maintain the traditional TNBTW format of interviewing a guest and focusing on useful skills or tools that can help you improve your tech writing skills; the other episode will be a behind-the-scenes look into what Kate’s working on, struggling with, or thinking about in her daily tech writing life.

—

Contact The Not-Boring Tech Writer team:

We love hearing your ideas for episode topics, guests, or general feedback:

• Email: [email protected]
• Bluesky
  
  

Contact Kate Mueller: 

• LinkedIn
• knowledgewithsass.com
  
  

Contact KnowledgeOwl:

• KnowledgeOwl.com
• LinkedIn
  
  

—

Transcript

Kate Mueller: [00:00:04] Welcome to The Not-Boring Tech Writer, a podcast sponsored by KnowledgeOwl. Together, we explore topics and hear from other writers to help inspire us, deepen our skills, and foster our distinctly not-boring tech writing community.
In today's episode, we relaunch the podcast and introduce you to our new (and hopefully not-boring) host. Spoiler, I'm neither Jacob nor Jared. My name is Kate Mueller. Hi, nice to meet you. When KnowledgeOwl decided to relaunch The Not-Boring Tech Writer, they asked me to serve as the host and my first thought was immediate panic. Am I a real enough tech writer to host this show? I feel more like a 'Pinocchio' tech writer. What if everybody figures it out? I'm not formally trained in technical communication or technical writing, and I do have formal training in both writing, generally at an information management, but I've never been super confident or comfortable with the title of tech writer. I've been doing technical writing for at least the last 15 years. I started with documenting databases I designed and built for coworkers to give them instructions on how to use them. Then I moved into user guides for third party software my company used, and eventually ended up writing support documentation for the software companies I worked for. I've helped write app copy and microcopy in two software products. I've written release notes and product newsletters and 'Getting Started' guides, and I've taken thousands of screenshots. Working at KnowledgeOwl, I've brainstormed and advised customers on all kinds of things, including information architecture, content best practices, authoring and auditing processes, and getting buy-in and managing new knowledge base rollouts. I've created the first formal knowledge based places. I've migrated from one knowledge platform to another. I've trained people, I've mentored younger writers. I've spent the last 15 years taking complicated, highly technical tools and breaking them into easier to understand components. I've written documentation for technical and non-technical users and I've had to find ways to explain and simplify things that, 48 hours before, I'd never even heard of.

Kate Mueller: [00:02:26] These are all valuable technical writing skills, but I still kind of felt like an imposter offering to host a podcast about tech writing. I can't really say why I didn't feel technical enough to host this podcast. I guess, I don't write code, so there's that. I've never created a DOCSIS code pipeline from scratch. I'm not very good with using automating tools or anything that involves code, especially conditionals and loops, and I haven't been formally trained on it. I didn't go get a certificate or anything in technical communications. I just feel like I'm always aware of how much I don't know and all the deep expertise I don't have. I'm not a wizard with analytics, I've updated API docs, but I've never created them from scratch. I feel like I have a pretty good depth of knowledge, but a lot of my knowledge has grown only when I had some kind of immediate, urgent problem to solve, rather than in a methodical, systematic, or formal way.

Kate Mueller: [00:03:34] But the more I thought about it, the more I realized that a lot of the writers I know feel this way. There's this slightly nagging feeling all the time, because I'm not an expert at literally the entire domain, I'm somehow not a real tech writer, and everybody else is. I've shied away from using the phrase 'tech writer' to describe what I do. Sometimes I've called it support documentation or product documentation. Sometimes I call myself a documentarian. I've also called myself a product champion. When I dug into other podcasts on tech writing, it felt like there were good podcasts for technical communication and good podcasts for general writing tips, but it didn't feel like there was anything fitting what I needed. Where's the podcast for those of us who don't feel like real tech writers, but who are, nonetheless, writing technical or support or product documentation on a regular basis? You're listening to the answer. That's what The Not-Boring Tech Writer is now, or at least that's what I hope it becomes. My focus in relaunching this podcast is on carving out a space for writers like me. If you feel like you write pretty good docs, but you dread when someone asks you to set up analytics, or you want to roll your eyes when marketing requests, SEO changes, or writing docs is just one of many hats you wear and you're worried you're not good enough at it. Or maybe you're secretly convinced you aren't qualified enough for your role. You found the right place, welcome home. We'll get to feel like mild imposters together. And together, we'll be exploring topics and hearing from guests to help inspire us, make us feel less alone, and teach us more about the skills and areas we don't feel as confident in.

Kate Mueller: [00:05:29] Here's what you can expect from The Not-Boring Tech Writer moving forward. I'm aiming for a two episodes per month schedule. One of those episodes will be, what I'm affectionately calling, the 'Kate Sounds Off' episodes, kind of like this one. You'll get to hear me talk about what's top of mind for me and my tech writing journey, what I'm working on, what I'm anxious about, whatever. My deepest, darkest tech writing secrets. Then the other episodes will stay true to the existing Not-Boring Tech Writer format, where I'll interview guests about the things I, and hopefully you, want to learn more a...

In this episode I’m talking to Swapnil Ogale, a Technical Writer Advocate for Redocly based in Melbourne, Australia, who is also a Community and Conference Manager for Write the Docs. He gives us the inside scoop on arranging Write the Docs events conferences both in-person and online, and talks to us about the importance of advocacy for technical writers.

The Not-Boring Tech Writer - feedback survey

Twitter - Swapnil Ogale

LinkedIn - Swapnil Ogale

Write the Docs

We’re back after a short and unexpected break! Sorry to keep you waiting!

This episode you’ll hear Kat Stoica Ostenfeld, an accomplished tech writer living in Copenhagen in Denmark. A linguist by credential, she says diplomacy is the key to being an effective documentarian, and shares how her translation and applied linguistics background helped her find common understanding and success in the world of technical writing.

Additional topics: Beautiful limestone buildings; puppy chat; spouse sacrifices; documentation as its own pillar; language proficiency vs successful communication; the meaning of “documentation”; linguistics applied; the diplomacy of being a tech writer; full stack teams; writing rage; linguistic detective work.

The Not-Boring Tech Writer - feedback survey

Twitter - Kat Stoica Ostenfeld

LinkedIn - Kat Stoica Ostenfeld

Medium - Kat Stoica Ostenfeld

Write the Docs

Tekom

Kat's talk from WTD Sweden 2020

In this episode, I’m excited to be speaking to Caity Cronkhite, Seattle-based founder and CEO of Good Words LLC. 

We talk about her experience of starting up as a tech writer both in-house and freelancing, before starting and growing her own successful business in the technical writing industry, and the successes and struggles of operating Good Words LLC in these strange and unpredictable pandemic times.

Additional topics: U-Haul montage; Something Big and Impactful; (not) going the way of the startup; nurturing your network; adult, painstaking colouring.

Read the full transcript for this episode here.

Show notes:

• Good Words LLC
• Email Good Words LLC
• LinkedIn - Caity Cronkhite
• LinkedIn - Good Words LLC
• Society for Technical Communication

In such a complex and fast-moving industry as tech writing, it can be interesting to see how burgeoning tech writers get started - and become successful. 

Enter Philip Kiely, author of Writing for Software Developers and owner of PK&C, the world's smallest conglomerate. He graduated from Grinnell College in May 2020 with a degree in computer science, and has only gone onwards and upwards from there!

This week I speak to Philip about being a new(-ish) entrant to the tech writing game, becoming a first-time author of a successful book, adventures during his time studying abroad in Budapest, Hungary, and how he managed to infiltrate a hackathon in Iowa during a blizzard! 

Read the full transcript for this episode.

Show notes:

• Philip Kiely’s website
• Writing for Software Developers

After four exciting years hosting The Not-Boring Tech Writer—the podcast that gives listeners the skills to break the stereotype that technical writing is a boring career—I’ve passed the podcast along to longtime sponsor KnowledgeOwl, a knowledge base software company. 

This sobers me, admittedly: What began as a medium to connect with colleagues whom I’ve admired since university gradually become a resource for new and seasoned technical writers alike to learn the skills they need to break the stereotype that technical writing a boring career. 

Now, as I begin a new career, KnowledgeOwl—who, as you’ll learn in this episode, has a relentless commitment to supporting the technical writing—will ensure the philosophy you’ve impressively fostered through this podcast continues. 

In this episode, Chief Executive Owl at KnowledgeOwl Marybeth, joins the podcast to share her vision for the podcast. In addition, upcoming host and KnowledgeOwl employee Jerrard Doran joins to share how he’ll further the philosophy while adding his own unique approach. 

Thanks, all, for your support of The Not-Boring Tech Writer—and hope you enjoy this episode. 

Read the full transcript of this episode.

Technical writers must ensure their help resources, such as documentation and video tutorials, are useful for their users. Therefore, they study language, design, and Support tickets—gathering all the context they need to ensure users can accomplish their task. 

But get this: Through feedback loops such as quizzes and interviews with subject matter experts, you can create usability tests that transform the way in which you measure the effectiveness of your documentation.

That’s why in this episode, we have Mariana Moreira on the podcast: Technical Writer at Zup Innovation and Community Manager of Brazil’s budding technical comm community, Tech Writing BR. 

Joining us, as well is Jerrard Doran at KnowledgeOwl—longtime sponsor of The Not-Boring Tech Writer—to discuss usability tests from a knowledge base software company’s perspective, as well. 

In this episode, you’ll learn everything you need to know to begin creating usability tests for your organization.

Show notes: 

• Tech Writing BR
• Knowledgeowl knowledge base software
• Skill #11: Surviving in the Dev World
• Mariana on LinkedIn

Technical communicators wield the power of plain language to ensure their readers find and understand the information they need to complete a task—no matter how complex.

Basic design principles, such as alignment, contrast, and other principles you’ll learn in this episode, give your documentation that extra lift it needs to engage readers throughout your documentation. 

That’s why in this episode, we have Laci Kettavong on the podcast: Marketing and Member Coordinator at Stoke, a coworking space based in Denton, Texas—and also a former technical communicator in both industry and academia, deploying design principles for several different mediums. 

Joining us, as well is Jerrard Dorran at KnowledgeOwl—longtime sponsor of The Not-Boring Tech Writer—to discuss design principles from a knowledge base software company’s perspective, as well. 

In this episode, you’ll learn everything you need to know to begin using basic design principles in your documentation. 

Show notes: 

• Non-Designer’s Design Book
• axe-con
• Knowledgeowl knowledge base software
• Laci on Twitter
• Laci on LinkedIn
• Laci’s blog

Folk working in technical communication—whether they’re academics or practitioners—through their own unique skill sets, perspectives, and experiences, often discover best practices to excel at their job. These hard-earned insights would likely benefit others facing similar challenges; however, silos often keep folk in technical communication from quickly disseminating what they’ve learned. 

That’s why Dr. Chris Lam—technical communication professor at the University of North Texas—created CrowdsourceTPC: a crowdsource platform that gives folk in technical communication and opportunity to share their insights and little wins—giving others an opportunity to use and adapt them for their own needs. 

In this episode, Chris joins us on the podcast to discuss the inspiration behind CrowdsourceTPC and how others can make the most of the platform. 

Show notes: 

• Chris Lam on LinkedIn
• CrowdsourceTPC

For the civically-mind technical writer, there’s a growing movement in cities across the world where technical writers can use their skills to better their community. It’s called Open Data Day: an annual celebration of open data groups around the world partnering with local governments to use open data to achieve a shared goal in the community. 

From analyzing environment data to tracking public money flows, open data day gives citizens—from data folk to advocates—an opportunity to get the data they need to take action in their communities.

As a tech writer, you may not initially see how your skills fit into open data. However, as you’ll learn in this episode, success open data day’s need compelling narratives to complement outcomes, tutorials to teach people how to access the data for their own uses, and much more—all areas in which the tech writer succeeds. 

That’s why, in this episode, I have Jesse Hamner and two-time guest on the podcast—longtime open data advocates who’ve seen first-hand the value of the tech writer. 

In this episode, Jesse and Kyle help us understand the value of open data and how the civically-minded technical writer can get plugged into this exciting movement. 

Show notes: 

• Open Data Day
• Skill #14: Contributing to Open Source Projects
• Jesse Hamner on Twitter
• Kyle Taylor on Twitter