Latest / The Not-Boring Tech Writer / Kate sounds off on cognitive capital and learning
Transcript
- Kate Mueller: [00:00:05] 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 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 early August. There have been three great white shark sightings in my area in the last couple of weeks, and we're currently in the midst of serious air quality alerts thanks to Canadian wildfires. So I feel like I'm living in two different summer blockbuster films, neither of which seems likely to end well. First, my progress update: since my last episode, I've updated another 15 articles, taking my grand total to 565, which doesn't seem like a lot of changes and is way lower than my usual monthly totals. In my defense, July was KnowledgeOwl summer camp, so I was prepping to teach at least one, 2.5 hour long class each week last month and offering support or co-teaching a second class each week as well. So I was plenty busy, just not with a lot of content updates. We also made some progress changes in July, so I'll no longer be a true solo-writer. Our support and success Owls, who serve as champions for features and bug fixes, will now be jumping into the fray. Kate Mueller: [00:01:45] Thanks to this change, I'll be drafting some minimum viable documentation guidelines for them so they have some checklists and streamlined guides to prep docs changes to go with app releases. And, I'll be trying to adapt to being a reviewer more than a primary content creator, so some of my authoring and updating numbers will go down. But in theory, a lot more content will be getting out the door. Side note: if any of you have helpful tips on making the transition from solo writer to contributor manager, please reach out. I could use all the help I can get. I am also sadly still battling my mouse problem, although it has improved. I had so long of a lull without catching a mouse that I stopped baiting my traps. And since my temporary hole blocking measures seemed to have been the most effective solution, I decided to replace the temporary blocks with an expanding foam. And then, while I was removing steel wool and spraying foam into the holes that came from, I noticed a hole I hadn't previously found. And as I moved to spray it, I watched a mouse run out from under a nearby car and into the hole directly into my basement, right in front of me. The thing almost ran over my foot to get there. So my mouse problem is not fully solved. And while I could have gotten frustrated or upset, instead I found myself laughing and thinking back to Manny [Silva’s] episode when he noted that a customer reporting a doc as broken is basically them telling you that your test has failed. Kate Mueller: [00:03:27] That scampering mouse was telling me that while my overall prevention strategy had worked, I hadn't been as thorough as I needed to be. My test had failed. As with any negative docs feedback, while I'm not thrilled that it occurred, I am thankful that I discovered a weakness and that I'm able to take some actions to address the situation. Although I'm not sure I've ever updated a doc as maniacally as I sprayed foam directly into that hole. I loved working on the summer camp classes, and my limited availability for docs work helped surface the need for more writing help, which led to the larger process discussion and changes. So in many ways, having more restrictions on my time has led to a lot of improvements, just nothing that I can report in tidy, satisfying numbers to all of you. Though, I am a process gal, so process improvements can often leave me feeling more accomplished than numbers do. But what the month also surfaced was something significantly less positive. I live with a chronic illness that causes a lot of issues, and the nastiest symptoms I manage are fatigue and brain fog and not fatigue as in “oh, I didn't get enough sleep, I'm a little tired,” but fatigue as in, “oh, I'm not sure I can find enough energy to get out of bed, even though I just slept 11 hours.” Both my fatigue and my brain fog get a lot worse the more stressed I become. And I'm not talking about stress here in the sense of, “oh, I feel emotionally stressed about a thing,” but stress as in, “oh, I feel physically, or emotionally, or psychologically rundown.” While I absolutely love, love, love teaching classes, prepping a 2.5 hour lecture that has very few breaks, and then delivering that lecture was physically and mentally stressful for me, and repeating that for four weeks in a row was wildly stressful. So I spent the majority of July in a constant state of near-total exhaustion, battling a brain that got less and less coherent as the month went on. The last couple of weeks, I basically taught my class on Thursday and ended up sleeping away most of the weekend, scraping together just enough energy to repeat that process the following week. That experience has reminded me, in a very visceral way, of why I connect so strongly with a lot of Ryan [Macklin’s] empathy advocacy work, and why I feel it's so important. In the average week, I can read some pretty wildly complicated docs and still have them make sense. But by that last week of July, last week, complicated docs were completely beyond me. I would have flailed and struggled and given up, because the reality I brought with me to anything I read was a physiologically struggling reality. Kate Mueller: [00:06:42] My body undermined my ability to interpret and understand things, no matter how much I might have wanted to interpret and understand them. I described this in the episode with Ryan as being aware that readers come with both ambient stress and acute stress, and we want to try to minimize our contributions to any form of stress. Ambient stress is a general stress. You're feeling burnt out. You're overwhelmed by reality. You're short-staffed. You know, it's kind of a general, almost malaise, form of stress. Acute stress might be more like having an urgent deadline, just having received bad news or facing a sudden layoff. So for me, as my symptoms got worse, both my ambient and acute stress levels climbed, which made my symptoms worse, which made my stress levels higher. It's a demoralizing cycle anyone living with a chronic condition knows well. “But what on earth does this have to do with tech writing, Kate?” I'm sharing this because as technical writers, we may want to minimize the demands we make on readers, but we aren't psychics. We don't know what stressors our readers come to our docs with. We can't personalize our docs to individual readers. And even if we could, optimizing for one individual might create a subpar experience for someone else. What we can do is to do our best to make style, formatting, and architectural choices that minimize the stress we ask our readers to incur when they use our docs. Kate Mueller: [00:08:28] I think Ryan and I ended up calling this cognitive capital in that episode. We want to lower the cognitive capital we demand from our readers, so they can achieve whatever they're hoping to achieve in our docs and get back to what they were doing before, at least with no more stress, and maybe even with a little bit less stress. And if I think about it, this theme underlies so many of my guest episodes this year. But it's especially top of mind for me now as I think about the type of docs I most needed those last couple weeks of July. And I didn't need much. I didn't need fanciness. I mainly needed consistency. I needed things to follow some fairly basic best practices. If I had to generate a review checklist for what I most needed then, here's where I'd start. Number one: provide a summary, synopsis, TLDR or 1 to 2 context setting sentences at the start of a doc or the start of a section. I needed things that clearly spelled out if these were the droids I was looking for, and therefore if it was worth using the limited cognitive capital I had to read the doc. Number two: use strong page titles and headings. Avoid catch-alls like “frequently asked questions” except as temporary holding pens. I found myself getting incredibly irritated at headings and page titles that were too long, too vague, or that sacrificed clarity for cleverness. Kate Mueller: [00:10:10] I didn't have enough energy to be clever, I just needed the facts. Number three: format your content consistently using semantic elements like sequential headings. The more consistently you follow your own conventions, the more a reader can learn them and know what to expect. These elements give very clear indications of how content and concepts connect or relate, and I needed less text when sequential and nested headings were used properly. It's good for humans, it's good for screen readers, and it's good for AI—that's the trifecta win. Number four: use callouts, warnings or admonitions sparingly, but in consistent ways. Occasionally, breaking the flow of things can help draw attention to important details. But if you use too many or you use them inconsistently, they can be overwhelming or confusing. I developed a deeper appreciation for consistently formatted and consistently placed callouts, since they demanded less from me while still conveying the info I needed. And number five: reduce screenshots. Use them to orient at critical moments, highlight key steps, or validate progress in a confusing process. And for accessibility’s sake, make sure those screenshots have appropriate alt text and are just supplementing the text rather than replacing text. I did run into a couple docs where screenshots were used excessively, and I found them to be overwhelming and it made the page seem so much longer and intimidating. I really developed a heightened appreciation for screenshot restraint. Kate Mueller: [00:11:54] As you can tell, these are some fairly basic best practices. And yet, as I was doing research to prep for my classes, I continued to find docs that violated them. At the start of the month, that wasn't a big deal, but by the end of the month, I honestly just closed sources and didn't skim them if they violated too many of these principles because I didn't have enough energy to battle them. And frankly, I had enough alternate sources to fill the gap. And speaking of not having enough energy, let's pause for a quick break. Kate Mueller: [00:12:29] 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:12:52] It would be easy to get a bit down about the fact that my docs velocity really plummeted last month, but I'm again reminded of something Liz [Argall] mentioned a few episodes ago: how sometimes letting ground lie fallow to recover is just as important as actively cultivating it. I spent a lot of July not having enough time to really push forward on my docs projects, while also spending a great deal of time talking and teaching about how to use KnowledgeOwl. And because it's me, I use those trainings also as a kind of Trojan horse to share some tech writing best practices. Kate Mueller: [00:13:35] This meant that I was thinking a lot about authoring and reviewing workflows, about content re-use, and content formatting and presentation. I also got to spend a few days researching style guide best practices to teach one of our most conceptual classes to date—called Style Guides 101—and that's reminded me of the fact that while so many of us talk about how important continual learning is in our profession, it's also often really hard to carve out time for things you don't have to learn immediately for a given task. There's the learning we do for new tools, domains, or features so that we can document those things for our audience. Or, you know, to learn a tech stack at a new job. We pretty much always do this type of learning. Then there's the learning we do for tooling or scripting for ourselves, to try to make our lives easier or collect more data. We often can make time for this type of learning because we have a pressing question or problem or request to prioritize it. There's learning we do in some kind of formalized way, like attending a class or getting a certification. We may find it harder to do this, often for financial reasons, but even more so if we don't see a near future application for that content. But there should also be learning that's both less formal and less tactical. Kate Mueller: [00:15:05] We so rarely carve out time to go explore best practices in our field. If we don't have a semi-urgent reason or a problem to solve—well, I mean, I don't. I hope you're better at it than I am. But here's the case in point. Part of this big docs project I keep reporting on in these solo episodes has been applying the style guide I wrote to our existing documentation. To write that style guide, I pretty much just used some practices I'd learned from experience or heard about at conferences and applied them. I grabbed a base style guide, the Microsoft Style Guide in my case, and built an add on guide to that so I could get something together quickly. I had an immediate need, and relying on that existing knowledge was good enough, and it was good enough—then. In researching style guides to teach a class on them, though, I took a step back and looked at the much larger picture. I pulled resources about why style guides are useful, about different approaches to formatting them, about drawing a distinction between the style guide as a reference and the processes around creating content. I didn't spend forever and a day doing the research to prep for class, but I can guarantee you I wouldn't have made the time for it if I hadn't been teaching a class on it. I then put together a series of in-class exercises to encourage our participants to evaluate their current style guides and reflect on places they could improve them. Kate Mueller: [00:16:41] As part of the class, I also completed these exercises, and I came away with two full handwritten pages of ways I could improve both our style guide and our authoring guides. Especially with this new champion contributor model we're adopting. Through this lens, my previously good-enough guide was definitely not good enough. Those two pages are full of some fantastic ideas that will add clarity and thoughtfulness to a somewhat slapdash document, if I'm being honest. Those ideas will help me transition my team to a different authoring workflow and make better use of our knowledge base’s feature set. Kate Mueller: [00:17:23] If you've been listening for a while, it probably won't shock you to learn I ended up viewing my guides through the lens of content types. That is my theme—2025: The Year of Content Types. I realized that my current style guide was trying to be a mixture of reference and how-to documentation, with some how-to docs split out separately, but some wedged into the style guide itself. Moving forward, my plan is to more strictly split those out so I can give the how-to docs the care and attention they deserve, while keeping the reference material even more succinct and streamlined. I'm also currently prepping to teach a four-week Information Architecture Master Class in partnership with KnowledgeOwl. It will be platform agnostic, covering concepts and applications anyone can use, and I really can't put into words how much I'm loving digging into the research and geeking out about information architecture. I'm not sure I've had this much fun researching stuff since grad school, and it makes me wish I prioritized this more often. So here's my bit of advice from my very humbling July. Pick a topic you've been wanting to improve on and give yourself 2 to 4 hours to research it. Schedule it like it's a meeting. Ignore the whole rest of the world. Just get your research on. Treat it like you're researching and trying to prepare to teach a class. Create summaries of key points. Think of questions or exercises to help you apply what you're learning. In short, give yourself some informal but structured learning about something in our domain. Or if you don't have the discipline for that but do have some professional development budget, consider joining me for our Information Architecture Master Class in September and October. I'll do most of the researching for you, and I'll curate a list of some fantastic resources and exercises. And hopefully in all of that, you'll be able to carve out some time to do some deep strategic thinking about your information architecture and how you might want to improve it. But however you get there, this back to school season, give yourself some explicit time to learn about one area you've been meaning to learn more about and haven't been able to prioritize. Kate Mueller: [00:19:49] And if anyone gives you crap about prioritizing that over other tasks, just blame it on me. It's what I'm here for. To learn more about our information Master class, go to thenotboringtechwriter.com/learning. You can use coupon code “notboring” to save 40% off the list price. 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, please message us on LinkedIn or Bluesky at The Not-Boring Tech Writer, or email tnbtw@knowledgeowl.com. Kate Mueller: [00:20:35] The Not-Boring Tech Writer is co-produced by Chad Timblin, our podcast Head of Operations, 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.