Latest / The Not-Boring Tech Writer / Kate sounds off on stress reduction
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. Kate Mueller: [00:00:29] 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 May, just after Write the Docs Portland. First, my progress update. In the last month, I've updated around 100 articles to reflect changes to the article editor redesign. As part of those changes, I've changed the content hierarchy in three categories to be closer to what I've used in our feature subcategories. I somehow still have a solid 97 pages relating to the article editor that I haven't updated, I’m not quite sure how that's happened, and I'm also still unsure how many pages of editor-related features need updating. But at this point, I've gotten through about half of my original feature and concept punch down list, including a couple of the ones I most dreaded, and I'm just kind of chunking away at this as I have time. We've received a lot of feedback on the editor redesign, and we've already made some changes to the new design, so I'm weirdly a little glad that I hadn't gotten too far ahead on docs updates, because I'd just be making a lot of them again. Kate Mueller: [00:01:41] I've also helped with docs on a few new features, including small updates to our API endpoint documentation, writing some best practices for using URL redirect articles and categories, basically totally overhauling our broken link checker documentation because we hugely expanded the feature so that it now checks both broken and successful links and has a fairly different UI and different columns in the CSV export, and writing some guidance on robots.txt customizations to prevent certain types of user agent traffic. That one was fun to research. I also reviewed docs someone else updated when we finally transitioned advanced search to being the full find and replace feature we had always wanted it to be. So overall, it's been a really productive month. I've been balancing new or updated feature docs with the continuing article editor overhaul project, and I felt pretty good about that balance. I was also fairly busy with Write the Docs Portland since I was Writing Day Coordinator this year. I was prepping for Writing Day, doing things like reviewing project applications, coordinating with project organizers, and writing pull requests to update the project information on the website so attendees could figure out which project they were interested in. Plus, I was busy with the actual Write the Docs Portland conference last week. As always, the conference was a whirlwind of connecting with other like-minded folks, getting some awesome templates and tools to help improve my own work, and learning a lot about how other people are thinking about docs, especially when it comes to handling things like AI or workflows. Kate Mueller: [00:03:23] It's given me a lot to think about, and I'm still tired and having trouble adjusting back to the regular daily grind. But isn't that one of the beauties of attending or staffing a conference you thoroughly enjoy? And of course, I've also been reflecting on my interview with Florian Lefebvre, who is one of our first guests recruited through our Suggest a Guest form on thenotboringtechwriter.com and the first non-native English speaking developer I've interviewed. That's kind of a mouthful. Honestly, one of my favorite parts of this interview was Florian's story arc relating to docs. I loved that he admitted that when he first started at Astro, he felt lazy and didn't really want to do docs and that in hindsight, he felt his first few changeset docs weren't very good because he wasn't very enthusiastic. So to go from that starting point to where he is now, where he feels like a feature isn't complete unless it's documented so people can understand it and use it. This is exactly the kind of transformation I believe we all hope for with our less enthusiastic colleagues. Florian talked about wanting to maintain the quality of Astro's documentation so readers would have a good experience, as good of an experience in the docs he wrote as they did in the rest of the Astro docs. And he pointed out that good docs mean happy users and less support. Kate Mueller: [00:04:52] I love a good story arc, but I especially love it when it turns someone who wasn't enthusiastic about docs into someone who is a docs champion. It warms my heart and it gives me hope for humanity. It's clear that Florian's developed a solid working relationship with Sarah Rainsberger, the Astro Docs lead. That collaboration is key for so many things to work well, and I kind of love that we got to see that from his perspective rather than from hers. So thank you, Sarah, for encouraging him to apply to come on the show. I also really appreciated Sarah's use of the open talking and doc-ing meetings they have an opportunity to talk through docs that contributors have drafted. Florian said repeatedly how useful these conversations were for him. And I love so much about this. I adore the phrase, and I may repurpose it or borrow it or steal it for some of my own meetings. So thank you, Sarah.,But I loved that a big piece of these meetings seems to be Sarah reflecting back her understanding of the future based on what she read in the drafted docs. So these conversations serve as a way for her to provide first reader feedback to contributors, to speak directly with the maintainers who are building the features, and clarify her understanding or misunderstanding to identify ways to improve the docs before release. Kate Mueller: [00:06:18] Managing subject matter expert conversations is a big piece of most tech writers’ jobs. Arguably, we spend more time doing that than actually writing, and I like that Sarah's approach seems like it's more focused around clarifying understanding rather than nitpicking small details, although it does sound like sometimes when the big issues are decided, some good nits get picked too. But one of the things I've noticed collaborating with folks who aren't writers is that they expect reviews will be grammar nitpicking, and that's often what puts them off the entire process, or makes them more resistant or less enthusiastic. Keeping the focus well and truly on the subject matter that they are experts in is a great strategy for keeping them contributing and engaged. And it feels like Sarah's approach handles that well. It also seems like this format helps remove stress for contributors whose first language isn't English, since they have to worry a lot less about getting things perfectly right in their drafts. Instead, they can make a solid effort in the draft, but then rely on these synchronous talking and doc-ing meetings to work through any confusion or idiomatic differences that crop up. Kate Mueller: [00:07:36] 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:59] Florian's episode also found me returning to one of my somewhat familiar themes on this podcast: the idea of documentation as a stress reducer. Probably the two best episodes for this topic are episode 16 with Ryan Macklin and episode 17, which was my reflection on that episode. I'll link to both of those in the show notes. And in both of those episodes, I talk a bit about the distinction between ambient stress and acute stress, ambient stress being all the low grade stress that we carry with us various place–right now that might be economic or job stress, geopolitical stress, if you've got illness, or young children, all of those would be ambient stress. And then acute stress being like really specific things, like if you have young children and one of them woke up sick today, that would be an acute stress. If you had a meeting with your boss and it went really poorly, that would be acute stress. And so when we come to the documentation, we are bringing all of that combination of ambient and acute stress to what we're doing in the documentation. And most often when I've talked about docs as a stress reducer, I'm talking about reducing stress for your readers, whether your readers are your customers or your colleagues or some combination of those, good, trustworthy, reliable documentation can reduce stress in their lives in so many ways. Kate Mueller: [00:09:31] If you can give readers answers that they need, that they can feel confident in, and you can do so quickly, that is a significantly less stressful experience than hard to find, contradictory, or inaccurate answers. Just getting that help and getting back to what they're doing can remove acute stress, can help reduce ambient stress or a little bit of both. But Florian's comments reminded me that as docs leads, the processes we build, the guides we write, the ways we support and encourage contributors or reviewers, these are also acts of stress reduction and great service. They're just stress reduction for our contributors or our reviewers. These folks are also managing ambient stress. Both the dumpster fire that is 2026, but also ambient stress about things like, “I'm a bad writer” or “I don't really understand how this site is built, so I don't really know how my stuff's supposed to fit into it.” And they're also managing acute stress, whether that's the vagaries of their day to day jobs outside of writing documentation or stress around specific writing things that they're bad at, whether that's writing in another language or grammar stuff that they struggle with, or just that moment where they need to choose where this specific page should live in the docs site or what it should be called. Kate Mueller: [00:10:59] For large writing teams or cases where you desperately need subject matter experts or community contributions, a little intention on streamlining those processes to explicitly reduce stress can go a long way. And it feels to me, based on my conversation with Florian, that Sarah at Astro Docs has been nailing this process. And so it gives me a perfect excuse to talk about that a little bit. So first, she has those talking and doc-ing meetings I already mentioned. Also, Sarah, if you're listening, I'm really curious. I spelled this doc-ing with a dash, so doc-ing, I’m very curious how you spell it, but these talking and doc-ing meetings seem focused first and foremost on content and concepts, on making sure that the docs are accurately representing what's actually happening in Astro. And that focus alone feels like it does help reduce a little bit of stress for the people participating in the meeting. The episode didn't highlight this a ton, but the approach it sounds like Astro Docs uses is designed for collaboration and thoroughness rather than necessarily speed. So the Astro Docs Docs site (or Astro Docs Squared) makes clear that all pull requests, even those written by maintainers, must be approved by someone else. So the act of saying "this looks good to me" is still a meaningful contribution to the docs, even if you didn't write anything. Kate Mueller: [00:12:30] That's one way to get contributors over some of the ambient or acute stresses they have specifically around writing, to build more confidence in their contributions by making it so that they don't have to write to contribute. And this assumption of review also means that there isn't as much pressure to get a PR approved and merged quickly. It seems like thoughtfulness and good documentation lie at the heart of this process. But Sarah's process seems to also take the structuring and the stress reduction a step further. She doesn't make her contributors think about information architecture, content hierarchy, or cross-referencing. And I love this as an approach to managing contributions. I've taken a similar tactic with my feature champions internally here at KnowledgeOwl. So in Astro Docs' case, for the experimental features, all the documentation for that feature lives on a single page for the entire time that it's in experimental status, and it's only once the feature is being moved to stabilized status that that page gets broken up and incorporated into other places in the docs, like user guides or reference material. So this means that in those early stages especially, when a feature might go through a lot of permutation, docs contributions don't require a lot of thought on how to structure or where to put them. You head to the single page about that experimental feature and you update it. Kate Mueller: [00:13:59] That feels like maybe a small thing, but it feels like it reduces a ton of ambient stress for maintainers and contributors, while also encouraging more contributions for them by keeping the process so simple. There's all this stuff that they don't have to worry about to contribute to an experimental feature. And then once the feature has stabilized, Sarah helps split that single page into the different content types and components and figures out where they should live and how they should cross-reference each other. Basically, she gets to apply that big picture view that she has as Docs Lead and put it to use, instead of expecting other people to try to do that themselves. And so this is again, an act of stress reduction and an act of service to her contributors, because it removes a whole bunch of stuff that they don't want to think about that might cause stress or anxiety that they wouldn't know what to do with, and so might cause decision paralysis. At the same time, I have to assume that it helps her maintain some control over her site hierarchy and architecture, which is a space that she, as Docs Lead, is way more qualified to think about, but also a lot more comfortable thinking about than the average contributor. Kate Mueller: [00:15:16] I don't go to quite this level with my feature champions at KnowledgeOwl. We don't have the same kind of set experimental to stabilized feature development process, but for new features, if my feature champions are drafting documentation, I have them drop that documentation into an internal-only category called In-progress. And this lets me review what they've done to make sure we have the cross-references and explanations that keep the docs consistent. I also often will split pages up differently than the way they have, so I am leaning toward the idea of maybe having folks do a single page, and then I can extract from there. Maybe I'll borrow from Sarah on that one. But it means that I'm the one who's making decisions about things like content hierarchy and where things should live and what those categories or subcategories should be called. And we're really early in using this process at KnowledgeOwl. I only created it in the last year, but so far it seems to be removing stress from my colleagues while giving them the space to work on docs themselves, and that feels like a win-win. I was initially worried that my teammates would feel like I was being a control freak about the content hierarchy, and that was the piece for whatever reason that I thought they would be resistant to. And when I walked them through the process, I discovered that the biggest stress they had creating documentation was figuring out where it should live. Kate Mueller: [00:16:46] So they didn't view this as a control thing at all. They viewed it as a massive relief that they didn't have to make the decision, and it removed the anxiety of making the wrong decision, that they could outsource that to the person they consider to be the resident expert, which would be me. Those are way less stressful decisions for me to make because I'm in the docs all the time. I'm much more familiar with the hierarchy because I built it, and I don't have that same sense of anxiety about making the wrong decision because I make those decisions all the time. So it's just much lower stakes for me than it is for them. Kate Mueller: [00:17:24] So this month, I'm continuing to reflect on the ways that I can streamline my contribution and review processes to remove stress from my teammates while keeping the quality of our documentation high. It'll probably result in a little bit of trial and error, but I really like the idea of explicitly having conversations around: what are the things that stress you out the most about this process? Are there things I could remove from it that would make your lives better? And so if you're managing other writers or community contributions, I hope you'll join me this month in trying to adopt a similar framework of thinking about how to streamline and make those contributions easier and less stressful for the other people involved. Kate Mueller: [00:18:12] 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. I would be delighted to get some more folks who are as enthusiastic as Florian, and I'm so thankful that Sarah leaned on him to have him join the show. Please do this with your colleagues, coworkers, friends, etc. Kate Mueller: [00:18:56] 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.