Latest / The Not-Boring Tech Writer / Kate sounds off on docs symbiosis
Transcript
- Kate Mueller: [00:00:04] Welcome to The Not-Boring Tech Writer, a podcast sponsored by KnowledgeOwl. Together, we hear from other writers to explore writing concepts and strategies, deepen our tech writing skills, get inspired, and connect with our distinctly not-boring tech writing community. If you are passionate about documentation, you belong here, no matter your job title or experience level. Welcome. [00:00:30] Hello lovely, 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 in the middle of February, right after Valentine's Day, when all of that candy is on markdown and you're exercising self-restraint, or not, depending on how much you like hearts that taste like chalk. First, my progress update. Since my last episode, I've been catching up on some things for this podcast and updating some documentation based on recent KnowledgeOwl releases. I haven't updated any more of the API endpoint documentation itself, which is the big project I'm currently working on, but I have been doing some API docs housekeeping. I fixed several display issues with the API docs, and I tidied up my internal Postman collection to share it with my team, and I'm going to be doing a quick lunch-and-learn on that collection in the next few weeks. [00:01:28] Most of the last month I've spent putting the finishing touches on my change management toolkit. The toolkit is not quite released yet, but it's very close. Achingly close. So close I wish I could tell you about it, but I'm saving that for when it's actually available because I don't let myself applaud achievements until they're actually achieved. What I can say, is that I am not sure why I thought creating a framework from scratch would be relatively fast or straightforward, since it's been the complete opposite of that. It's been a good lesson that sometimes that distance between what you can see in your head and actually building the thing in real life is a broad, gaping chasm that you just have to throw yourself against for a while before you find a way across. But it's been good work to do, and as it's taken shape, I continue to believe it will be a great resource for KnowledgeOwl authors. I'm actually really proud of it, but also a little terrified of it. There's always that risk when you think you're creating an awesome resource that it's not actually going to be an awesome resource, but I am feeling pretty good about it, so we'll see. It's also been a really great reminder of how important it is to be both ruthless and thoughtful about prioritization, and to not try to overengineer solutions. My “Nice to Have” list is holding a lot of cool ideas, but it's also felt really good to draw sharp boundaries and not balloon my scope. And because of that, I will actually finish it hopefully this week, but we'll see. Kate Mueller: [00:03:06] I've had fun playing around with graphics for it and thinking about interactive elements, too, which is a bit different from my average support documentation. I've been trying to channel some of the conversations I had with Dennis Dawson and Bill Holland and thinking about both the visual aspect and how to keep people engaged. I'm still feeling my way into standards for those things, and I'm sure the tooling and the process that I use will change, but it has been really engaging to think about those visual and interactive elements. I normally do not love accordions, or tabs, or things that require you to interact with it to see the stuff you want to see, but I think there's a place for those things, particularly in more learning-styled or tutorial content, where you're really asking someone to go with you on a journey conceptually, and giving them ways to stay engaged with that feels meaningful. I'm still exploring ways that I could enhance that experience, collecting ways that other people have solved these problems. So if there's a site who's interactive or graphical elements you really like, please send it to me. I would love to check it out. [00:04:23] I've also been reflecting a bit on my interview with Bill Holland. One of my biggest takeaways from that conversation was that most of Bill's suggested best practices for working with a designer embody a lot of practices that are part and parcel of being a tech writer. So here's three key steps that stood out to me in this way. First, you start by providing a brief that explains things in detail, especially any special terminology or acronyms. You define what you want to get out of the project, what its intent is, and what the most important thing you want to communicate is. You assume that the designer knows nothing about the project or industry. This sounds like pretty standard tech writing stuff, doesn't it? Second, you compile and share mood boards, graphic samples, or video playlists that have an aesthetic you like, so your designer can get a feel for the style you're after. This, to me, is a little bit like, “Let me go look at how this genre has been handled by other people and find the examples of it that I really like, that I want to inform the docs that I'm creating.” This is useful both for the designer because they have this as a reference point, but also for you or your team, so that you have some concrete sense of what you want and what you don't want. And this gives something for all of you to refer back to as you're going through that design process, reviewing drafts, and providing feedback. And third, when you do receive designs or roughs back, provide solid, detailed feedback about what you like and what doesn't seem right, and tie that criticism back to your style samples or your brief or any of those front-loaded materials you gave your designer. If you need people higher up the food chain to sign off, get that sign off relatively early, especially for things like animation that can take sizable time and budget if they need to be reworked. Along the way, be prepared for a designer to suggest how something could be done better or differently, or adjusted to fit within your budget. Their job isn't necessarily to tell you what you want to hear, but to help you get the thing you actually need or want. [00:06:42] I was also struck by the similarities between the designer and tech writer roles. Both writers and designers end up having to explain the process and in some cases, help clients through that process. We may need to make the case for why our experience is valuable and worth its cost. We also need to figure out how detailed of an edit we should provide for feedback based on where we think our audience is at, how literal or nitpicky they might be, etc. Designers make decisions about how rough of a sketch or rough animatic they want to share with you. As writers, we make decisions about how rough of a rough draft we want to share. In both cases, setting expectations to frame the feedback you receive is absolutely essential. And to some extent, both domains are being impacted in interesting and potentially disruptive ways by AI. Whether it's by people believing that they can replace us wholesale with AI, or whether it's us practitioners exploring ways to use AI as one of many tools to streamline our workflows. Kate Mueller: [00:07:48] So there's just a lot of overlap there, which I did half-expect, but I was still pleasantly surprised by. The other image that stuck with me was Bill's description of how creating animation often functions like an assembly line, where different people might work on different elements or different stages. That image has stuck with me and really resonated with me in terms of thinking about it as a process overall, how a team would have people who specialize in different steps of the process, or even how a freelance motion graphics designer might contract out certain parts of the process that they don't specialize in to others. It also really helped me visualize how there are key points along the way, that if you don't adjust where things are going, it becomes an expensive nightmare to try to correct later. If I extend the assembly line metaphor, if somebody's really early on in working on the frame or the chassis doesn't say, “Hey, something in here doesn't add up,” by the time you get to finishing touches, the thing doesn't even run properly, steer like a car, etc. I know, we're doubling down on the Big Three assembly line references, I'm sorry. This is the Michigander background for both Bill and I. Kate Mueller: [00:09:11] I am curious, though, for those of you who are working on larger writing teams, do you have a similar type of assembly line mentality or specialization in your team, or are you mostly just distributing the same kinds of work equally across the team? Is it a “divide and conquer,” or is it “distribute and get stuff done”? Drop us a comment or an email. I'm debating if there's enough content here to merit a future episode, and your replies will help me figure that out. And last little side note, I had a lot of fun talking with Bill about the processes we used for the podcast logo and the animated intro he made for us. I will say I didn't do this to be self-centered. I just think that having real-world examples can be more illustrative and fun, and I hope it helped connect some dots for you or if anything else, you could see the logos that we said no to. The ghosts of The Not-Boring Tech Writer podcast logos past. Kate Mueller: [00:10:15] 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. [00:10:38] The big thing I've been mulling over with or sitting with lately, work-wise, is trying to balance the needs of documentation care and feeding—what I might call routine maintenance work—with the needs of larger strategic projects and how to navigate that lingering feeling that if I spend too much time on one thing, I'm neglecting the other thing. I often find routine maintenance work to be welcome respite when I'm feeling overwhelmed or unsure of what to work on. I know I've talked about this before, definitely in episodes 21 and 23, probably some others. It's work that needs to get done and the quality of your documentation definitely suffers if you don't do it. Then there are larger strategic projects like my change management toolkit or things like tooling changes, content reorgs, major style guide changes. Those kinds of things. These strategic projects are much more important in the big picture or the long-term. They usually require longer, more sustained effort, and because of their importance, they're consequently more likely to be things you have to report out progress on as well. All of those things can come with heightened scrutiny, or more people having opinions about or needing to sign off on the choices you make, or deadlines or milestones that have to be hit on a certain schedule, you may need to coordinate work with folks in other departments or teams. They're larger, they're more visible, and they typically have more moving parts. [00:12:15] It can feel like the large strategic projects and the smaller daily maintenance tasks are in conflict or opposition. You can't forsake the smaller daily tasks completely for strategic projects for long without things exploding, but you also can't endlessly tackle only small tasks and expect to feel like you're effectively moving the needle, strategically speaking, or that you're continuing to make the case for yourself or your documentation. You need them both, but it can feel like they're competing for your time, your energy, your effort, whatever. [00:12:53] That idea of competition is the thing I've been thinking about. I just finished reading Suzanne Simard's book Finding the Mother Tree, which is about her lifetime of research into forestry practices and communication networks. One of its themes that really resonated with me is her attempt to overthrow conventional wisdom that trees and plants in a forest are always in competition with each other. This comes up frequently in forestry circles. Once you do a clear cut and you go to replant, what's the most effective way to do that? And conventional wisdom for a long time was that you wanted to clear out everything that could possibly compete with the seedlings that you were planting. So that idea of competition is very much baked into a lot of those practices. And her research shows that, in fact, there's a lot of collaboration and community happening in forests, maybe far more of that than competition. [00:13:55] I found myself really also wanting to overthrow that same baked-in mindset when it comes to the dynamics between strategic documentation projects and maintenance work. We often view these as competing needs or desires. While it's true that time we spend on one does mean sacrificing time we could spend on the other, I'm really trying to embrace the mindset that this is a healthy tension rather than competition: a form of ebb and flow. Let me talk about that a little bit more. Research like Simard's has shown that trees share resources like water and nutrients through mycorrhizal networks, which are fungal networks for those of you who are not mushroom geeks like I am. They also communicate warnings about parasites and infections. For example, in times of drought, older, more established trees may feed water through these networks to smaller seedlings that would otherwise die. And obviously, that helps those seedlings ride out those tough times to continue to grow and flourish. And then eventually those seedlings become bigger, older trees who then pay it forward to the next generation of seedlings, especially if they're genetically related. Where scientists once only saw competition, we now understand that the dynamics are a lot more nuanced. Some species grow better when they're connected to other species. It was thought for a long time, at least in Canadian forests, that birch was a direct competitor of Douglas fir. And then, through Simard's research and other scientists’, it has turned out that Douglas fir often grow far better if they have some birch nearby. They share resources through the network. [00:15:40] This is the mindset shift I'm trying to adopt with my own sense of conflict or tension between strategic documentation projects and routine maintenance work. One can't exist without the other. If I don't do the big strategic projects, I'm not driving my documentation forward, I'm just maintaining the status quo. But eventually, that status quo isn't enough. If I focus all my energy all the time on big strategic projects, my existing documentation quickly becomes outdated or inaccurate. This lack of maintenance will undermine my documentation's trustworthiness and eventually undermine the resources we put toward docs. So instead of competition, there's a clear mutual symbiosis between the two. They each need the other to survive; a balance has to be struck here. And that balance isn't just in the documentation itself and the work that we produce, but also, for me anyway, in my energy levels and how I work and what I work on, too. Big strategic projects require a lot more energy for me. Deeper problem solving, more ideation, more thinking two or five or ten steps down the line to try to foresee consequences of the choices I make. And many days I love that deeper, more involved work. It's motivating. It's inspiring. It feels awesome. But that work also requires blocks of very focused, heads-down time for me that are then interspersed with these highly collaborative moments where I come up for air and I might pitch part of the idea to someone else, or have them review an early draft to see what their initial reactions are. For the podcast, that person is usually Chad. Shout out to Chad. For the toolkit it's been Veronica. Shout out to Veronica. Kate Mueller: [00:17:40] This approach is wildly different from my more routine maintenance work, which doesn't typically require the same level of focus, and it also rarely requires much input from others. I can do a lot of it on autopilot. It can feel Zen-like and focused, but it's not that same amped up, maybe more frenetic energy that the larger strategic projects need. And because of these differences, the two project types are really hard for me to context switch between. If I prioritize the strategic project, for example, it can be hard to shift from that big picture work into the weeds of daily maintenance work. Once my mind starts chewing on that big strategic thing, that's where it wants to stay until I'm exhausted or I need a break, or I've hit a point where I definitely need feedback from a collaborator before I continue. Often by that point, it's near the end of the day anyway. And conversely, if I'm in the weeds doing maintenance work, it can be hard to lift myself up high enough into that bigger picture of the strategic project. I find if I start the day in maintenance mode when I try to shift to the strategic project, I get hung up on much smaller details. I need to have a meeting or a break or some kind of buffer to facilitate that shift. But the idea of symbiosis and symbiosis instead of competition has really helped guide me. [00:19:15] Over the last two months, I've tried a few different tactics for maintaining a balance between these two needs. Around the holidays, when my calendar was naturally quieter, I set aside entire weeks to focus on either my strategic project or my maintenance. When I finally finished my 2025 project that I talked about in every solo episode last year, I set aside a week dedicated entirely to getting my backlog under control and banging out a lot of smaller maintenance tasks. I followed that up with a week that was basically a sprint on the toolkit, and I'll admit, this was a bit of a fail in terms of a week-long sprint, because it was right around the holidays and I already had holiday brain, and about halfway through I hit a wall on some of the big picture thinking because my brain had just checked out already, so I ended up pivoting back to maintenance work for a little bit of that. Once I came back from the holidays, my calendar was busy enough that I couldn't set aside entire weeks. So I basically started trying to designate certain days as strategic project days. Kate Mueller: [00:20:21] They'd be the one day of the week where I had few or no meetings, so I could block off a nice big chunk of time to flail around and try things, and then fail and regroup and eventually find a path forward. I tried to have these days coordinate with Veronica's schedule so that she'd be available when I did take breaks so that I could bounce ideas off of her or have her read in-progress drafts. On the days where I had meetings, or I needed to do podcast work to meet our publishing deadlines or whatever, I focused on routine maintenance, trying to work on the things that felt most important to keep my backlog under control. Am I doing this perfectly? No. Definitely not. I am now over a month past my delivery deadline for the toolkit, so I am struggling to find the right balance I would say. Or maybe there was a problem with the deadline originally, but I'm also extending myself a little grace on that, since I had some training classes and other unexpected commitments materialize in that month, and so all my deadlines had to adjust a bit. Time and time again, I've been told that priorities compete for my time. And this month, I'm really trying to embrace the idea that competition is not the metaphor I want to use—it's passé—and instead to figure out how those priorities complement each other or feed off of each other: what does that symbiotic relationship look like? [00:21:54] My strategic work is full of uncertainty and second guessing, but it also makes me stretch my abilities and the content we have, and it feels really inspiring. My routine maintenance work is a place of more security and quick wins, but it's not the most inspiring, it just feels good to check stuff off. I need them both to keep me going, and my documentation needs them both to stay relevant and to stay lovable. So this month, I'd encourage you to join me in this effort. Are there ways you can shift the narrative about all your competing priorities and to recognize the ways those differing priorities work together? Or are there ways that thinking about it in this new way can help you ride the natural ebbs and flows of your own energy? Does it work well for you to set aside a time block, or a whole day, or an entire week dedicated to a specific project or task? Or does the formal structure of that make the rebellious part of your mind immediately want to go do something else? (which often happens to me) Either way, we're never going to get rid of this tension, but we do have control over the metaphors that we use, and understanding the ways we do and don't work well within that tension seems important. I'm not sure if I'll ever fully kick the idea of it being a competition, but I'm doing my best to embrace the idea of symbiosis instead. Kate Mueller: [00:23:28] And I'd really love you to try it with me. And as always, 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, or if you'd just like to tell us what you're getting out of the show, please message us on LinkedIn or Bluesky @thenotboringtechwriter, or email tnbtw@knowledgeowl.com. You can also hit up thenotboringtechwriter.com and select “Suggest a Guest” to recommend yourself or someone else as a new guest. [00:24:08] The Not-Boring Tech Writer is co-produced by our podcast Head of Operations, Chad Timblin, and me. Post-production is handled by the lovely humans at Astronomic Audio, with editing by Dillon, transcription by Madi, and general post-production support by Been and Alex. Our theme song is by Brightside Studio. Our artwork is by Bill Netherlands. You can order The Not-Boring Tech Writer t-shirts, stickers, mugs, and other merch from the “Merch” tab on thenotboringtechwriter.com. You can check out KnowledgeOwl's products at knowledgeowl.com. And if you want to work with me on docs, knowledge management, coaching, or revamping an existing knowledge base, go to knowledgewithsass.com. Until next time, I'm Kate Mueller and you are The Not-Boring Tech Writer.