Latest / The Not-Boring Tech Writer / Kate sounds off on mice and iterating
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. Kate Mueller: [00:00:24] 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. I'm recording this episode at the beginning of March, eagerly awaiting the daylight savings time shift. I'm going to start this episode with a quick story. I promise it does relate to documentation eventually, but it begins like this: my house has mice. I've suspected this since last spring when I found an acorn stash and some plant pots I had in the basement. We rent our house and I have to go outside and around the house to get into the basement, so I don't go down there a lot. In the winter, I go about once a month to check our heating fuel levels, and I store the plant pots and patio chairs down there in the fall and bring them out in the spring. Otherwise, I don't really go down there for months at a time. After I found this acorn stash, I had some suspicions, but I didn't have a lot of evidence that these were mice. They could have been chipmunks, I don't know. Or that they were actually living in the house. I was living in this lovely state of blissful ignorance until about two weeks ago when I was taking a bath and I heard a mouse scratching around in the wall right behind my head. Kate Mueller: [00:01:41] As a good tenant, I contacted my landlord who wanted to use glue traps to get rid of them. I have some major issues with glue traps, so for the last week or so I've been baiting live traps with really tasty things and then relocating the mice I trap to a local nature preserve. At the time of this recording, I have now relocated six mice. You might be asking yourself, Kate, why on earth are you bringing up mice on a podcast about tech writing? I do say that these solo episodes are about things I'm thinking about, and I'm definitely thinking a lot about the mice, but where is the relevance? I'm bringing it up because it's a lot like docs updates, kind of. The problem started out feeling somewhat small and not worth prioritizing, and then suddenly it wasn't small and needed to be prioritized immediately. Once I started working on it, I chose a solution that was a good solution, but ended up being way more work than I originally thought I'd signed up for. As I've gotten into it, the problem I thought I was solving is far more widespread than I initially thought it was. So not only am I doing more work because of the solution I picked, but I'm also doing more work because the problem turns out to be much bigger than I thought. Kate Mueller: [00:03:02] The good news is, because I'm already kind of in the thick of it and working on it and in mousetrap mode, I don't feel as overwhelmed by the larger scope of it. I'm also paying attention to what seems to work better and iterating on that so my processes are becoming streamlined. If, wait let's be optimistic, when I get to a place where the scratching and the wall totally stops, I will then put in some preventive measures to try to avoid having this happen again. See, it's exactly like a docs project, right? Am I beating myself up for mice appearing in my rented house? No, this is what mice do. I live in Maine. They want a warm place for the winter, I totally get it. By the same token, docs get outdated. It's in their very nature. We're not documenting static, unchanging things, we're documenting tools or processes that are constantly evolving. Docs tend toward staleness without human intervention, and that also isn't a thing I need to beat myself up about. Let's just accept that it's in their nature. Then when we identify problems, we focus on solutions and implementing processes to mitigate the future recurrence of that same problem. If that story doesn't tell you all you need to know about how my current massive docs update is going, I'm not sure what will. Kate Mueller: [00:04:31] As I mentioned in my previous solo episodes, I've been continuing to update a ton of our support documentation to reflect both navigation changes and UI changes we rolled out. I've also, because it's me, made it a slightly larger project by including some style guide changes and updates. Although my initial ambitions about really elaborate content type templates have fallen by the wayside, I am still using some content type ideas and structures as I make these changes. And since I've promised you updates, here's my official update. Since we released the nav changes in mid-December, I've created or updated about 365 articles and deleted or archived another 20. In total, in a little under three months, I've updated nearly 400 articles. In the last month, besides making some updates to individual articles, I also reorganized an additional features subcategory thanks to content types, they really helped, which has taken my total subcategory reorgs to five. This month I tackled a much larger overhaul, restructuring and rewriting a lot of our search documentation. So, not bad. Though I'm still a far cry from being done, I'm enjoying the process, and I'm oddly happy that I decided to combine some style guide updates with the navigation and UI changes. Along the way, I'm paying attention to many of the accessibility details that Kenzie and I talked about last episode, while also updating screenshots to match our current style guidelines, formatting callouts more consistently, removing things like 'this feature allows you to do X' and reworking them to say things like 'use the feature this way to do X'. This is a bit of a spoiler about our next guest episode too, by the way. I'm sure my velocity is likely a bit slower because of the added style elements, but I feel much prouder of the final products. Speaking of final products, here's a message from our sponsor. Kate Mueller: [00:06:48] This episode is sponsored by KnowledgeOwl, your team's next knowledge base solution. You don't have to be a technical wizard to use KnowledgeOwl. Our intuitive, robust features empower teammates of all feathers to spend more time on content and less time on administration. Learn more and sign up for a free 30-day trial at knowledgeowl.com. Kate Mueller: [00:07:14] Today I'm grateful for having a good, concise style guide and working with content types. These two changes have made these updates less stressful, despite me adding more style changes into them. They're giving me a better mousetrap, as it were. Oh god, is that cringe? I'm leaving it in anyway. The best example of how this is helping me is in my overhaul of our search documentation. First let me set the stage. The search docs were the first feature support docs I wrote at KnowledgeOwl when I started in 2018, almost seven years ago now. As with many of our first attempts at things, as the years have gone by, I have grown to like them less and less. When I wrote them, we didn't have a style guide or content types or even a consistent content hierarchy. We also weren't sure how much detail people would need on search, so I erred on the side of exhaustive documentation. None of this is likely the approach I'd use today if I were writing them from scratch. I've updated that documentation in fits and starts as we've rolled out changes over the years, but it's one of those tasks that I knew was going to be a total beast so I kept focusing on smaller changes that were more sustainable. I figured I'd get into it and it would be so nasty and overwhelming that I'd never finish it, so I just kept putting it off. The docs clearly showed that approach, if you looked closely enough. They didn't consistently align with our current style guide, and some of them felt redundant or repetitive. There were definitely docs that were the first things I wrote when I started here, but I knew I couldn't get around updating them this time. Because about a month ago we rolled out some changes to the search settings as part of the UI updates, so I couldn't just keep kicking that can down the road. I mean, I tried. Don't get me wrong, I tried. I tried some fast and dirty changes that only covered the new settings, and I hated it. I felt really frustrated with the content. Then I was like, maybe I can just do a slight reorganizing here and maybe that'll be enough. It felt better, but it still didn't feel great. Kate Mueller: [00:09:39] This time instead of sidestepping it, which is what I've done every time in the past, I asked Erica, one of our Customer Success Owls, for some feedback. I showed her the changes that I'd made already, then I described where I was struggling and asked her some questions, and in that process she gave me a huge warm fuzzy. She said that she really liked the changes I'd been making in the feature subcategories, that those changes were making it much easier for her to find what she needed, that the structure just seemed to make more sense, it felt a lot more predictable, and she wanted me to do more of that here. This was the first piece of concrete evidence I've gotten that some of the content type inspired changes were working, and it felt amazing. I guess it was exactly what I needed, because I rode that high into a way more significant rewrite of the existing search content and almost a total reorganization of the entire category. Admittedly, I did spend longer on making these changes than I had originally hoped, but it's also the first time in years that I've actually felt proud of these docs. I mean, it's me, so I still have some stuff I want to do in there. There were some pages that I totally sidestepped. They're not a high priority, they're not impacted by the new settings, and honestly the content in them may change because we have some additional search functionality that we're currently testing. I just accepted that this stuff might change really soon anyway, I don't think this is the best use of my time. Basically, I accepted those messes for future me to have to clean up. But they're going to be much smaller messes than what I had before. I'll toss a link in the show notes to the search docs in case you want to go poke around and maybe judge me, give me some more feedback. That idea of iterative improvement, of doing better when you know better. Kate Mueller: [00:11:45] That reminds me of part of last episode's interview with Kenzie Woodbridge. One of the lines that has stuck with me from that episode was Kenzie's observation that we often leave physical building, construction, and accessibility to the experts. But because we're all creating content all the time, content accessibility isn't something we can just leave for the experts. We need to think about it and incorporate it as we're able to. If you've been listening to the pod this season, maybe you've picked up on some of the same tech writing themes I have. That we all continuously learn new things, whether that's tools or tech stacks or domains. That we often need to get feedback or knowledge from people far more knowledgeable than us. And that in the midst of that, we're still trying to get out docs that feel like an improvement without getting paralyzed by how much we could or maybe feel we should do. All of that might just be a nice way for me to package up the idea that we're constantly being reminded of how much we don't know, and of all the ways we aren't experts, and of all the ways our docs could still be better, but I believe the people who make the best tech writers, documentarians, or whatever title you use, are those who enjoy that sense of constant learning and improvement. It's an interesting thing to both know you aren't an expert in something, but to also try to do it anyway. Accessibility best practices are a good example of this. It could be easy to throw up our hands and say, I'm not an expert in that, I wouldn't know where to begin. You begin with the bits you do feel confident in doing. Kenzie's suggestions boiled down to four things: one, use actual headings. Don't just style normal paragraph text to look like a heading. Two, use sequential headings and don't skip levels. Three, use link text that has more meaning than 'see more' or 'click here'. And four, add alt text to images. All four of these aren't particularly hard. They're also best practices for content generally, not just for accessibility. They help with sense-making and wayfinding activities, they increase information sent, and they help buoy your search engine optimization. Kate Mueller: [00:14:08] They're the kinds of improvements it's a lot easier for me to prioritize because they meet multiple needs at once. Am I an expert in accessibility? No way, far from it. I know I have so much more to learn in this area. But as with my search docs, I'm going to keep doing better when I know better and I'm not going to beat myself up for stuff I didn't know how to do seven years ago, or five years ago or three years ago. I'm just going to recognize that I have to continue to keep learning and improving as I go. Improvements like this are one very concrete way that we get to make our little corner of the universe just a little bit better. These days, in 2025, it can be fairly overwhelming to participate in reality or to feel like anything you do makes a difference. I would suggest that it's these times that make small actions that much more important. These are things we can do. I can make my docs a little easier to understand, and a lot more accessible, so that my readers have a better time while they're in them, and hopefully spend less time there and more time on the things they most care about. I may not be able to make the whole world inclusive right now, but if I can make my docs even a tiny bit more inclusive and remove that extra little bit of stress or friction, that's a small force for good. We need more of that right now. This month, I'm encouraging you to think about your doc's to-do list, and to focus on the tasks that check multiple improvement boxes while also feeling like they're moving you in the direction you want to go. They don't have to be big changes, they don't have to be huge, grandiose. I'm not telling you to go reinvent your entire information architecture or apply content type templates everywhere. No, it just needs to be something that's an improvement. That you're putting that small extra bit of good out into the world. That's it, the bar is pretty low. I think that's maybe a good note for me to wrap up this episode on. Thank you for listening, if you have ideas for topics or guests, if there's a bit of the tech writing world that your life would be improved by hearing an episode on, please message us on Bluesky at The Not-Boring Tech Writer, or email tnbtw@knowledgeowl.com. Kate Mueller: [00:16:46] The Not-Boring Tech Writer is produced by the lovely humans at Astronomic Audio. With editing by Dillon, transcription by Alan, and post-production by Been and Alex. Chad Timblin is our podcast head of operations. Our theme song is by Brightside Studio. Our artwork is by Bill Netherlands. You can check out KnowledgeOwl's products at knowledgeowl.com. And if you want to work with me on docs, knowledge management coaching, and revamping an existing knowledge base, go to knowledgewithsass.com. Until next time, I'm Kate Mueller and you are the not-boring tech writer.