Latest / The Not-Boring Tech Writer / Kate sounds off on beliefs and maintenance work
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. 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 at the end of September, during what feels like the resurgence of summer. First, my progress update. Since my last episode, I got sick with Covid again, as you might be able to tell from my voice, which put a huge damper on me making a lot of progress. But I did manage to improve my total count by 40 edited articles, bumping my grand total from 618 to 658. Most of those 40 articles were all relating to functionality in our Account menu, which was the last large section of the site navigation that had been overhauled that I hadn't really touched yet. Also, the number is a little misleading because I did make more updates than that. It's just that I updated roughly 20 articles that had already been included in this total when we released changes to our Glossary feature. Because this project is neverending, some of my other work is being hidden in those numbers. The exciting moment for me in all of this was that once I got through the chunk of the Account menu, I realized that my official audit punch-down list now has maybe 50 articles remaining that I know I need to change. Kate Mueller: [00:01:48] And then once I go through those 50, I'll do some additional spot checks to figure out if I've overlooked anything in that punch-down list. And of course, now that the light at the end of the tunnel is so much closer, the team is debating some additional changes to the navigation. So I have this feeling that I will finish last year's changes just in time to start a major round of this year's changes, which is, of course, how these things go, right? Since I'm still recovering from Covid, and I don't have a ton of voice, and I'm trying not to cough during this, I'm going to try to keep this solo episode just maybe a little bit shorter than normal. But I did want to spend some time sharing my reflections on Fabri's interview. Fabri mentioned that part of why he developed the Seven-Action Documentation model was out of frustration—frustration that people were applying frameworks like Diátaxis without critically thinking about them or engaging with them. And one of the takeaways I was most left with out of the episode was the fact that that's not how I've used either Diátaxis or the Seven-Action Documentation model. Rather than viewing these frameworks or models as being exact prescriptive guidelines or requirements for changes that I should implement, I've had more of a, I guess I would call it a dialogue with them. Kate Mueller: [00:03:13] I found elements of them that really resonated for me, that felt really meaningful. And then there were some sections that felt maybe less relevant or less meaningful. None of that prompted me to slavishly change my overall documentation site structure, which I think is part of how people often implement both of these frameworks or models. The process that I went through of figuring out what resonated for me and what didn't, that honestly really helped me gain a lot of self-knowledge about my own opinions and beliefs about documentation. At one point in our interview, Fabri pointed out that all developers tend to be very opinionated about preferring certain languages or tools, or frameworks over others. And he said something like, “So why not us?” And I've been thinking about this idea of being allowed to be opinionated since we recorded the interview, and I will be the first to say that I am a fairly opinionated tech writer. There are certain things that I believe very strongly in, as you have probably noticed, since these solo episodes are often a place where I share those opinions and sound off on them. But for me, engaging with frameworks like Diátaxis or models like the Seven-Action Documentation model are time well spent because they help me surface the ways I'm ignorant about my own opinions. Kate Mueller: [00:04:46] Fabri also talked about this in the interview, about the fact that most of us do have an internal model or framework that we are often subconsciously applying. And this is something that I think the two of us are in complete agreement on: the true value of frameworks or models like these isn't that they tell us what to do, but that they help us interrogate ourselves to uncover, to refine, maybe even to better express the internal model we're already using. It helps us make the subconscious conscious or the accidental intentional. And the more aware you are of your own beliefs, biases, preferences, opinions, whatever you want to call them, the more you can have productive conversations about them. It might be a good way for a team of writers to have thoughtful conversations about the things they're each opinionated about, and through those conversations, to come to some kind of team consensus on the model that you all want to use and enforce. I mean, using models like this, I'm definitely finding value from them as a lone writer, because it's forcing me to decide, in that process of deciding whether I agree with something or not, whether it resonates for me or not, it's helping me to both better understand, but also to speak more thoughtfully to others about the ways that those beliefs and opinions are informing the documentation I'm doing. And so I think this could be generally a very good exercise for a lone writer as well, just to be able to better articulate to managers or other teams or departments why you're doing things the way you're doing, to kind of make the case for the way you believe things should be. Kate Mueller: [00:06:40] For example, engaging with Fabri's Seven-Action Documentation model and interviewing him made me very aware of how much I truly do believe that documentation helps readers with appraisal, and that for me, this is a very core belief, but one that's been kind of hidden among the depths. I mean, yes, I've talked a lot and often at a very high level about how good product documentation is itself a form of good marketing. I know documentation can serve that purpose because I have used documentation that way. I have helped make decisions about whether I was going to use certain tools or services, in part based on the documentation they had available. But as I was talking about it with Fabri, in the context of the model, and really thinking about the user needs surrounding appraisal, I realized that it's kind of changing the way that I approach my own documentation to be a little more thoughtful about appraisal specifically as a user need, especially with things like, for example, how I write feature overview pages. I'm not crafting a specific content template for those pages. Our features are often so very different that I haven't felt like that would be a very good use of time, because there isn't necessarily a set template version of “I need exactly these things”, but what it is prompting me to think about is to consider the idea of having some kind of checklist of user needs for different content types or different pages within my documentation, and that for my product feature overview pages, appraisal as a user need would be incorporated into at least one of those checklist items that I'd be reviewing and editing for. Kate Mueller: [00:08:41] Fabri talked about this in the interview in the sense of considering a user journey for each feature or different user types, and making sure that you have content that explicitly addresses all seven of the actions within his model. I think that also could be a really fascinating way to do it, but I'd encourage you to spend some time with the model too. Fabri clearly is excited at the idea of being questioned or debated about its efficacy, so I'd encourage you to poke him with your questions or your “Yeah, but” moments as well. He seems really excited for that. And I'm a little disappointed that the community hasn't engaged as much with it. Kate Mueller: [00:09:23] 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:46] Being quite sick with Covid again also made me way more aware of the ways that different tasks require different energy. I've been spending a lot of time this past year thinking structurally about the Support Knowledge Base. I've been rearranging a lot of my content hierarchy in my sort of second and third levels, or maybe more like third and fourth levels. Not top-level. Let's just say not top-level. I've been reformatting individual pages. I've been giving some thought to whether changes to other sections of our docs should also happen, especially in the land of reorganizing. I'd tightly scoped myself to all of our feature-related documentation when I started doing the content type work, and the clarity and consistency that I think those changes are providing in the features make me want to implement similar structures in other top-level categories. All of that is really good work. It's strategic, it's big picture, it's creative, and it's wildly engaging. But I can't do that kind of work all the time. I had to take a week off of work with Covid, and when I first returned to work afterward, I was putting a lot of my energy into the information [architecture] master class that I'm teaching, and I didn't have the energy or the focus for any other kind of highly involved creative strategic projects. Kate Mueller: [00:11:21] Instead, I ended up setting aside some time to just slog through a bunch of tedious individual doc updates around the navigation and UI changes. While I was in there, I made sure that those updates aligned with our current style guide, and I updated screenshots to reflect the new UI and our new screenshot view style guide requirements and all of that stuff. Just maintenance work basically, right? And maintenance work is not glamorous, but it's also work that I had the energy and focus to do while I was still recovering from being sick. And Fabri talked very briefly about maintenance work as well in the interview, he said something like: “I also had these spaces where I felt like a gardener of content, happy with these flowers and tending to the quality, doing maintenance work. And sometimes you need that to recharge. So it's good sometimes to do that.” And while I think gardening is potentially much bigger than maintenance work, so I maybe slightly disagree with him there, I do totally agree with him that maintenance work is a place I can go when I need to recharge. My team knows this because I often call it productive procrastination, because I'm usually putting off doing some bigger or more involved thing by doing a bunch of these smaller tasks. But at the same time, maintenance work is not negligible work. It's often actually fairly important. Many of these are documents that have been inaccurate since we released our major navigation changes in December of last year, and the inaccuracy within them has been a massive embarrassment to me [chuckle]. Kate Mueller: [00:13:11] I hate knowing that there's a chunk of my work out there that's outdated. One of my core beliefs about what makes good documentation good is that it needs to be trustworthy and accurate. And here I've spent over nine months knowing that some of my documentation was out of date. And then I come on this podcast and I talk about it, so I get to broadcast that mortification to the whole world, which just, it’s - so subtle, so subtle. It adds to the delight, I guess I would say. But one of the things Fabri and I discussed about personal growth and development is that when we get stuck doing any one thing all the time, we stagnate. Whether that's content strategy or information architecture or tooling or maintenance work or SEO–it doesn't really matter what the thing is. The nature of tech writing is that the role and the work generally does demand that we do a variety of things, and our own growth also demands that we do a variety of things. Fabri called it shapeshifting, which I kind of love as a term. I think it's a great way to think about it, and I'm anticipating that October will be a lot of maintenance work for me, since I'm still juggling the information architecture master class, which does suck up a lot of the creative strategic energy I have. Kate Mueller: [00:14:37] This bout of Covid is lingering and nasty, and I find that I'm still struggling to do much beyond that master class. So I'm trying to be really realistic about what October holds for me and what's reasonable to expect October to hold for me. And so I've just kind of decided that it's a maintenance month for me. And honestly, I think it's great. My docs benefit from me setting aside time for tedious maintenance work, and especially when I'm burnt out on other things, the maintenance work still makes me feel like I'm contributing in meaningful ways. I can still log off at the end of the day and feel like my docs are better than they were when I logged on that morning. And you know, if you've been dealing with illness in some way, just that feeling of productivity, the feeling of contribution makes a big difference. And I suppose I could maybe beat myself up about this, but I'm not. I'm just sort of taking the month as an experiment. I periodically do this. I kind of have to because I live with a chronic illness. But I've decided to treat October both as a maintenance month but also as a sort of self-reflection month. And I'm reevaluating or trying to just be aware of which writing tasks or projects feel good and aren't awful to complete when I know that I'm low on a lot of my energy measures, right? And conversely, which writing tasks or projects feel much harder? I think it's really good to do these kinds of personal check-ins on your energy and your attention, and what feels like it's filling up your cup and what feels like it's emptying your cup. And doing that, you know, once a quarter or once every six months, once every year, whatever cadence makes sense for you. Kate Mueller: [00:16:35] I'm doing it right now because I kind of have to. Also, fall feels like a good time to do it. We're all just human, right? We're all trying to ride the ebbs and flows of our energy as reality changes around us. And I would encourage you to join me this October in paying attention to what's filling up your cup and what's emptying it, because that self-knowledge, very much like the self-knowledge we get when we consider or try to use frameworks or models and use them to question our own beliefs and assumptions. The self-knowledge we get from observing our own energy levels and what's buoying us versus dragging us down can make us a lot more aware of our strengths and weaknesses and makes it much easier to weather adversity gracefully, I guess I would say. So consider this your invitation to join me in mapping your tech writing highs and lows for the next month. Or if you're like “Kate, please, no more self-reflection. I'm so over it,” if you've been needing an excuse to do some maintenance work, let's just pretend that we're doing a docs sprint together. We can all do some maintenance work here in October. I always feel like that's a good thing to do heading into the holidays anyway. Kate Mueller: [00:17:53] 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 frankly, 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. Kate Mueller: [00:18:22] 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.