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:
—
Contact The Not-Boring Tech Writer team:
We love hearing your ideas for episode topics, guests, or general feedback:
Contact Kate Mueller:
Contact Lorna Mitchell:
Contact KnowledgeOwl:
—
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 ...