Latest / The Not-Boring Tech Writer / Kate sounds off on docs as an act of service
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:20] 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 right after the US Labor Day, so 8000 emails telling me that the sale ended last night. And first, my progress update. Since my last episode, I took a week off. I had an actual vacation. It was lovely. And my grand total is up from 565 to 618 articles. About 23 of these were article updates to reflect the changes in navigation and UI that I've been working on since this season started. The other 30 were totally new content for our just-launched Owl Analytics feature, which is KnowledgeOwl's first foray into a fully in-house analytics suite. So I had to write all of the initial documentation for that, set up instructions, key analytics terms and concepts, detailed explanations of what different reports and drill down options do, and some general guidance on using the feature. That obviously took priority over all of the updates I'd been working on. Honestly, I'm not particularly into analytics, so this was definitely one of those times where I had to immerse myself in a new domain, make sense of it for myself, and then try to make sense of it for my readers. I got a few teammates to review the majority of the docs before they went live, and I got really positive feedback on them, so that felt good. Kate Mueller: [00:01:55] Let's see, quick summer recap. July was all about summer camp and August was all about Owl Analytics, and I'm really looking forward to having a bit more time in September and October to chip away at some of these longer running projects, and catch up on all the things I had to hit pause on to manage both of those big efforts. Kate Mueller: [00:02:17] What I haven't hit pause on is reflecting on Sarah Walker's episode, and there are three ideas from that episode that I want to spend some time on today. The first is a concept Sarah shared: Asteya or non-stealing. I really loved that she talked about how a lot of folks interpret this as not stealing physical items, and instead she focused on something one of her instructors had told her, which is not stealing people's energy or time. Gifting people more time is such a precious thing these days, isn't it? When I end a meeting early before the scheduled time, I always like to think of it as giving people extra time in the day. I know, I know, I'm not giving them more time in the day, but I'm giving them time they thought was spoken for that they're now free to do whatever with. Kate Mueller: [00:03:14] Thinking of my writing efforts as an extension of gifting people with unexpected free time is helpful. I especially appreciated Sarah's reframing of using style guidelines and conventions to consistently structure documentation. Rather than focusing on a lot of the kind of standard benefits of using them—so things like accessibility, AI, or even pedantic reasons, Sarah focused on the fact that they establish predictable patterns that help readers find what they need faster or in a less stressful way. I'm thinking of this as: style guide adherence is an anti-theft device. By having a predictable content hierarchy and consistent layout, formatting, language use, we reduce the mental energy readers need to engage with our documentation, which means we steal less energy and time from them. This might also be a callback to Ryan Macklin’s episode on the idea of energy theft and cognitive capital. Clearly, these are things I like to spend time thinking about, and I appreciate that a lot of my guests are in that same space. The second idea from Sarah's episode that I want to unpack is that writing great documentation is an act of giving great service. Sarah didn't explicitly say this, but I did. It's probably the third or fourth time I've mentioned documentation as an act of service, or talking to subject matter experts and being clear and concise in what you need as being an act of service. I talk about this a whole bunch. A big reason for that is because great service is the North Star within KnowledgeOwl's mission. So it's a phrase that I throw around a lot in my work life, and the ways that we talk about giving great service at KnowledgeOwl are deeply informed by Zingerman's model for giving great service. And if you're not familiar with the Zingerman's Community of Businesses or ZingTrain, check out the show notes for some more links on how they define giving great service. Kate Mueller:[00:05:23] But in a nutshell, Zingerman's and KnowledgeOwl both have a three step guide to giving great service that goes something like this. Step one, find out what your customer wants. Step two, get it for them, accurately, politely, and enthusiastically. Step three, go above and beyond, or go the extra mile. You can reword this however you want. At KnowledgeOwl, when we train new owls in this process, we stress that finding out what your customer wants, step one, is typically the hardest part. Humans often don't know the right words to use or the exact thing to ask for. Or we think we want one thing, but it turns out what we actually want is something else. A good support or success person will help get to the heart of your question and address that, even if it's not remotely the question you began by asking. And at KnowledgeOwl, we often use a Disney service example in training this: how Disney teaches their cast members to handle the question, 'what time is the 3:00 parade?'. An average support provider will generally answer with the time. But that's not usually what guests are asking about. I mean, that answer is already in the question, after all. Right? What time is the 3:00 parade? Why? It's at 3:00. But a great service provider recognizes that what the asker really wants to know isn't what time the parade is, but it's things like, what time the parade passes by particular locations in the park, or the best places to view the parade, or what time they need to leave somewhere else so that they can get to the parade on time. Giving great service and writing great documentation means that you're trying to provide answers to questions your readers might not even know how to ask. They don't know your product, or your domain, or your company processes. They just know they have a problem or a question, and they want answers on how to fix it or answer it. We, as tech writers, spend our time learning how things work so that we can create documentation and save other people the time, energy, and effort to figure it out for themselves. How is this not giving great service? Kate Mueller:[00:07:47] Typically, step two, the step to get what they need accurately, politely, and enthusiastically, is the easiest part of giving great service. Once you've actually figured out what someone wants or needs, you typically know whether that's something you can help with or whether it's not. This is, in many ways, the bulk of the documentation we write. It's information that at some point someone is going to need, whether that's instructions on how to complete a particular task, or a conceptual overview of how something works or is architected, reference materials on different settings or options, or tutorials on key skills. We create the resources that often get shared in step two. So we're kind of embedded in that great service process from the get go. Kate Mueller:[00:08:38] And, well, what about step three in giving great service? To go above and beyond, or to go the extra mile. This loosely ties into the third and final idea from the episode that I want to unpack, and I'll share it with you after this break from our sponsor. Kate Mueller: [00:08:55] 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:09:18] The third and final idea from Sarah's episode that I want to unpack isn't something we spent a lot of time on in the episode, but it's the idea of craft. Sarah made one comment about it that stuck with me in a really concrete way. She said something like, isn't that a great way to live? Especially nowadays, just to have some small part of your life be a little less stressful, be a little less frustrating, be a little less unknown—to have someone craft something for you, to learn how to do the thing that you need to do. Oh, Sarah, I love you for this. The idea of craft has come up in a number of episodes this year. I think Marcia Riefer Johnston’s episode is probably the one where we talk about it the most. I think our previous conversations around craft had been discussing the craft of writing. The techniques, the tools, you know, all of the stuff that we do when we create documentation. And what Sarah's comment really got me thinking about is adding on to that the idea of crafting something for someone else. I'm not just creating these docs because I believe they enhance the product experience, or because they might help us get more customers, or because it's my job, or because I'm skilled at it, or because I enjoy doing it. I mean, all of those things are true. They're all reasons that I write docs. But I'm also creating them for other people. In some cases, I'm writing docs and thinking about people I know well, and trying to write documentation in a way that will get them back to what they were doing faster. Kate Mueller: [00:11:08] If you've used user personas, it's kind of that idea, but for me, it's a little bit different. So because I came up from the support side at KnowledgeOwl—I worked support for a number of years while I was doing documentation, and then I stepped back from support to move more heavily onto the product side, but I kept doing documentation the whole time. And because I started on the support side, I can picture specific customers who I know well when I work on docs. I mean, some of them are no longer even customers at KnowledgeOwl, but they were distinct personalities to me. So many of the people who request features are people I've interacted with on the support side at some point, and that experience gives me a lot of knowledge about them. I know some of the struggles they face within their organization. I know that they sometimes face an uphill battle, rolling out features that require their IT department to get involved, and it's a big bureaucratic thing for them to have to submit a request and wait for it to go through the proper channels. And because I know that, if it's a feature that I know IT is going to have to be involved in, like setting up SSO or an SMTP configuration, I craft streamlined docs designed for them to share with their IT team that is just the set of facts that the IT admin would need to have. And then I craft separate stuff that's more detailed and nuanced for things that my authors are going to want to be able to do with the feature. I can picture a couple of my favorite solo writers, and I can try to put that hat on for a little bit and focus on time-saving tricks and tips for them. And then I can think about the politics of some of the larger writing teams I know, and focus on ways for them to ensure consistency in their content or reducing stress in their review and update process, knowing that they've got a lot of cooks in the kitchen. Kate Mueller [00:13:17] And the same thing applies for my internal team. I write internal docs for the KnowledgeOwl team, and I do it [because] somebody needs to. I do it because I know it will save them time, but also because I know what their work lives look like and what their personal lives look like, and how precious that bit of saved energy and effort can mean. So I'm writing docs for Anne, who has a young child who just started daycare. I'm writing docs for Erica, who spends part of her day crafting beautiful paintings, and for Veronica, who manages migraine pain, sometimes crippling migraine pain, and for Pete and Sue, who definitely would rather spend time building features and fixing bugs than trying to track down that one Slack thread about why we built the thing the way we did three years ago. Kate Mueller: [00:14:10] I'm writing docs for these people. And this is the piece that feels like it's lost in a lot of the AI bubble right now. Documentation isn't merely transactional. I mean, it can be transactional, but there's often a lot more to it than that. Done well, it's an act of caring for others, of respecting their time, of giving them a form of artisanal service, of consciously crafting a low friction experience for them. Because frankly, the world can be a hard, thoughtless, uncaring place, and this is one little corner where we can defy that. We can, and we do, craft with care. If we do it well, most readers won't ever realize how much work goes into it. It's like design work or house cleaning or probably repairing things for people. Folks only notice when you do it poorly. When you do it well, they have no concept of how much work it takes. But like Sarah, I know that this work does make the world just the tiniest fraction of a bit better. I mean, your management may not, frankly, probably doesn't care about that. Maybe your coworkers don't either. That's okay. What matters is that you do. The act of sharing knowledge is as central to our humanity as, I don't know, opposable thumbs, walking upright, using language and tools. Doing it through technical writing may be a more recent evolution, but that doesn't make it any less important. We're still sharing knowledge. Kate Mueller: [00:15:58] I suspect some gut feeling about this is why I try to avoid using the word “users.” You've probably noticed I mostly use the word “readers” or sometimes “viewers” instead. I like to think of the people engaging with my docs as people first and foremost. And so I'm just a human writer crafting information for another human to try to share it and also make their day a little bit better. And sometimes it works. You know, sometimes I'm good at that. Sometimes I miss the target a little or a lot. And I will say, updating some of my older categories and articles, I do find some super cringeworthy moments where it was clear that I was just, like, overwhelmed, trying to spit out a doc really quickly, not really thinking about the ideal reader experience. But what hasn't changed for me in the seven years I've worked on KnowledgeOwl's documentation, is my level of care and audience awareness. It's evolved over time as I got to know our author base and our product better, and as I've matured as a tech writer, for sure. But I don't think I could do this job well without that piece of humanity. Great docs are an act of great service. Kate Mueller: [00:17:15] We gift knowledge to others, and we gift it wrapped up in a package of care and thoughtfulness. Now, more than ever, let's recognize that what we're creating with our documentation is a knowledge sharing community. It's mostly made up of people we will never know or see or hear from, but that doesn't make the community any less real. We make connections between ideas, which in turn helps our readers make connections between our documentation and the work they do. And if we do our work well, those very same readers might be able to pass on a little bit of that saved stress or energy to others in their lives. Granted, this isn't some huge heroic gesture. I mean, we're not solving world hunger or curing cancer. I don't know. Nuclear fission. None of those things. But it's the kind of small, everyday gestures that we humans benefit from in a thousand small ways. I want to live in a world where humans thoughtfully do things for other humans, and one of the ways that I can create and participate in that world is through documentation. So this month, I'm focusing on reader experience. I'm trying to find all those small ways I can go the extra mile in my docs. To think more consciously and deliberately about the choices I make, the visual assets I use, the content layouts I'm using, subcategories or content hierarchy choices I'm making, because I want to build something for someone else, and I want to do it with craft and care. Kate Mueller: [00:18:59] I hope you can find something similar this month to add that extra little bit of craft into your work. And 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 and be one of those few listeners who gives feedback, please message us on LinkedIn or Bluesky at The Not-Boring Tech Writer or email tnbtw@knowledgeowl.com. Kate Mueller: [00:19:38] 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.