My current in-flight projects include updating nearly all of our documentation to reflect major changes to our user interface, which includes changes to screenshots, navigation options, and section/subsection labels. I’m also working on my long slog to convert all our screenshots from .png to .webp format. As I make all of those updates, I’m bringing our content into line with our current style guide (the first time I’ve used an explicit style guide in the KnowledgeOwl Support Knowledge Base).
I recently finished teaching my first Knowledge Management Master Class with KnowledgeOwl. This was mostly a success, though it was a sharp learning curve for me and I’m already full of ideas on what to do differently next time. It also humbled me since it made me view my own docs through the lens of all the best practices I was suggesting people employ–and realizing how often my docs fell short.
For me, the most fascinating takeaway was really digging into the concept of concept types or information typing. I’ve never done this as an explicit, intentional exercise. After researching various approaches, I’m sold on the underlying concept. My plan is to create some templates for each major content type, using The Good Docs Project’s templates as a starting point). I’m then going to use those templates as I update content in our Features category to test and refine the templates before gradually applying them to the entire knowledge base. I’ll be using tags to track my progress and identify the content type for each page, too. In Episode 5, I’ll report back on how I’m doing in my endeavors!
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 KnowledgeOwl:
—
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. Hello fellow not-boring tech writers. I'm Kate Mueller, and this is one of our solo episodes where I share things I'm thinking about or working on, or both. I'm recording this episode in early December, right after Assad's ouster and the murder of the UnitedHealthCare CEO, just for some context. So first up, what am I working on? I'm in the midst of making a lot of updates to the KnowledgeOwl support knowledge base. KnowledgeOwl has released a lot of UI changes in the last couple of months, which of course I got behind on, so now I'm working to get our screenshots and text updated from those changes, while knowing that there are more changes coming in the next few months too. This has been a lot of changes. We changed our whole color palette, we changed a lot of the user interface key elements, we also just rolled out a totally different left hand navigation so I've got my work cut out for me. But it's a good exercise because it's prompted me to really evaluate how useful a lot of those screenshots are and whether we actually need them. In particular, there are a lot of older articles where I used screenshots of code as a final example for some of our step by step documentation, and I'm gradually replacing those screenshots with formatted code blocks just to reduce the screenshot maintenance burden.
Kate Mueller: [00:01:41] I've also been updating screenshots. We're moving away from PNG format and into WebP format, just to try to keep our file sizes a bit smaller and maybe give our SEO a tiny bit of boost. That change came out of me writing our 'image best practice guide' for customers and actually researching image best practices. So that's been a fun change. And last but not least, after years of having a fairly vague style guide, or no style guide, I've written a clear one. So as I make all of these updates, I'm bringing the text into alignment with the new style guide. All of that has already been in flight for a few months. I also recently finished leading a Knowledge Management masterclass with KnowledgeOwl. And as the old saying goes, the best way to learn something is to teach it to others. So I'm thinking a lot about things like content types, information architecture, information scent and findability and good metrics for success. Teaching the class was really humbling to say the least. It's kind of impossible for me to teach a class on this stuff without feeling mildly embarrassed at all the ways my own docs don't follow the best practices I'm talking about. And to be honest, this was the first time I've really had the time and space to sit down and critically view my documentation through some of these lenses, these big pictures.
Kate Mueller: [00:03:12] I'm usually so busy trying to keep things up to date that I don't really take that step back to look at the big picture. And now that I have, I'm overflowing with ideas on how to improve my docs. So many ideas, and I've had to really sit down and evaluate and try to pick just one to focus on. So top of mind for me today is one of those ideas, content types. The masterclass really made me research and discuss content types, and I find that I keep thinking about them and thinking about how I haven't been intentionally or consistently using them to structure our content. I mean, clearly our docs have survived this long without me doing that, but I've been thinking about ways to make it easier for more members of our team to contribute to the support KB. The style guide standardization has been a big piece of that, but I believe content types with templates are the next step. They would make it much easier to onboard another writer, or to ask other owls to update docs in my absence.
Kate Mueller: [00:04:15] For those of you familiar with content types, I'm thinking mostly about the common information types used in frameworks like Dita. The content, task and reference. Or the four types that Diataxis uses, explanation, how to guide, reference and tutorial. And for those of you who've never heard of content types, I'l...
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 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]...
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.
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