The Not-Boring Tech Writer

In this solo episode, Kate shares an update on working with content types, muses about the idea of a Documentation Hierarchy of Needs, and reflects more on Janine Chan’s interview (S3:E4) and how we talk to ourselves about being tech writers.

—

I may have overcommitted myself in Episode 3. I have been incorporating content type work into my massive content audit, but after working on four of the nineteen Features subcategories, I realized it was taking too much time and I had to refocus on my main task of updating content to match our UI and navigation releases. However, I like the information architecture decisions this has helped me make and the clarity it’s bringing to the docs themselves and how I organize them, so it’s a project I intend to continue.

Making these kinds of priority decisions is something we all have to tackle all the time. But the content type work got me thinking: I’ve used an intuitive content type sense for a long time. I suspect I’m also using an intuitive decision-making framework for prioritizing my docs work. What would an explicit framework for that look like? In talking this over with a colleague, I realized I wanted a Documentation Hierarchy of Needs. I discovered that MongoDB created exactly this for their documentation overhaul once upon a time and wrote this blog post about it. I briefly run through their Hierarchy of Needs and how my decision to temporarily deprioritize content types might fit within it.

I also reflect more on Janine Chan’s episode (S3:E4) and her point about reframing the way we talk to ourselves from “I’m not technical enough” to “I don’t know how to do this… yet.” And I share my own suggestion for handling that narrative problem.

—

We love hearing your ideas for episode topics, guests, or general feedback:

Join the discussion by replying on Bluesky

—

Kate Mueller: [00:00:02] 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:18] Hello fellow 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 at the very beginning of February, soon after the Society for Technical Communication's announcement of its bankruptcy and closure. While I was never involved with STC, I know many writers who were, and I suspect that loss will feel like a gaping hole in our community for some time. Let's all be a little bit kinder to each other, shall we? First up, what I'm working on. In my last solo episode, I talked about content types and how I was planning to use a massive content update for navigation and UI changes as a time to start more intentionally applying content type templates to my docs. I recorded that episode about six weeks ago, and I promised I'd give you updates along the way, so here's my update. I'm not going to sugarcoat it, while I've made a good amount of progress on my massive content update, I haven't focused on the content type work the way I thought I would. Of the 19 feature subcategories in the support knowledge base, I updated four of them using some of those principles.

Kate Mueller: [00:01:31] On the plus side, I like the updates to those four subcategories. A couple of them were much older features, and the docs had become a bit unruly, and thinking about content types and user purpose and experience helped me begin the process of finally getting them into shape. That focus on user purpose helped me with some information architecture decisions, and I'm creating a consistent but mildly variable format that, so far, feels like a definite improvement. I also realized that this is time consuming work. I was overly optimistic about how large my existing project was, and how much time the extra work would take. Let's be real, I was making an already large project even larger, and each minute that I spent working on that was a minute I didn't spend updating other docs to have accurate navigation steps or UI wording changes. I've basically hit pause on the content type project for now, but my big takeaways from it are that I do like it and I'd like to keep doing it, I just don't think now is the best time. I need to get through this big project first. As Janine and I talked about last episode, I'm basically setting aside my perfectionism and focusing on improving my docs right now in the ways that feel reasonable right now. Even though I know I want to do more, I'm choosing to focus on changes that are already a solid improvement for my readers. No big deal, just trying to practice the advice I dole out all the time.

Kate Mueller: [00:03:10] Reflecting on all of that has also prompted me to think more explicitly about how I prioritize work in my documentation. Since the support KB is largely product support documentation, I view these docs as an extension of our product, and I want the experience to feel as intuitive and helpful as our product does. Having a disconnect between what the product navigation and UI look like, and what the docs say, has caused me a fair amount of stress. I'm basically deprioritizing the content type work until I feel the docs align more closely with the product. I'll still make some changes along the way, but it won't be the dedicated project I'd envisioned. What it's made me realize is that I'd like to define what our priorities in the docs are, to help provide a decision-making framework for myself or others moving forward, when big projects like this hit. That feels like it would remove some ambient stress and provide some guidance without being too strict or pedantic. I want something that's fairly loose, but also clear. A general framework, if you will. When I was talking about this with Marybeth, I realized that what I want is our documentation's hierarchy of needs. Maslow's Hierarchy of Needs, written in 1943, was about the categories of needs that human beings are motivated by. It's structured as a pyramid, with the understanding that you can't begin to address a higher need until a lower need's been met.

Kate Mueller: [00:04:40] It starts with what are considered basic needs, which Maslow split into two categories. Physiological needs like food, warmth, water and rest, and safety needs for security and safety. Then it includes two categories of psychological needs. The first is belonging in love, which includes intimate relationships and friends. The second is esteem needs like prestige and a sense of accomplishment. At the very top of the pyramid is a single block for self-fulfillment, the self-actualization needs around achieving your full potential, including creative activities. Since I only came to this idea yesterday in conversation, I haven't crafted a full documentation hierarchy of needs yet but I did discover that I'm not alone in thinking about documentation this way. MongoDB employed this same concept when they were redoing some of their docs. They published a blog post outlining their documentation's hierarchy of needs, which I'll share in the show notes. If you or someone you know was part of the MongoDB team who did this work, please reach out. I'd love to have you on the pod. Their identified needs in order were, first, existence and basic needs which included the tooling necessary to create and share the docs, as well as having actual content at all. Second was quality needs. In this case, they did some user research to define what quality meant to them, which included three points: be task or use case centric, come off as approachable, helpful and informative, and create emotions of confidence, excitement and determination.

Kate Mueller: [00:06:26] The third level of their pyramid is called findability needs, which included both navigation and search. The fourth was experience needs, which includes finishing touches and small tweaks to improve both the author's experience and the reader's experience. At the very top of their pyramid is contribution needs. Users wanted to be able to engage with the docs in meaningful ways. From their research, MongoDB described possible contribution needs as feeling that they can help docs improve, being able to report their own problems and joining a community. It's an interesting exercise and it's worth checking out their blog post. I'm not sure these would be the exact needs I'd use, but if I was using them, my priority decision that I just made could be the difference between quality needs versus findability needs. The accuracy of my docs reflecting the navigation options and UI elements is definitely a quality question. The content type work is more a mixture of quality to ensure that it's task or use case centric and findability to make sure it's organized in a way that makes sense. At any rate, I still have a lot of work to do on the navigation and UI updates. Of course, in the last couple of weeks we released additional changes so I'm now redoing some work I already did, too. I'm sharing all of this because I promised you I would, and because I really want to normalize the fact that we often are juggling reactive docs updates and proactive docs updates. Here, I'm trying to balance the needs of reacting to the changes in the navigation UI with my own desire to proactively improve the docs using content types. Reactive updates often take priority, they're a bit more like putting out a fire but we have to build in space to tackle those proactive, bigger projects too. Otherwise, we're just putting out fires forever and never building a new house. Before I mix any more metaphors, let's take a break.

Kate Mueller: [00:08:32] This episode is sponsored by KnowledgeOwl, your team's next knowledge-based solution. You don't have to be a technical wizard to use KnowledgeOwl. Our intuitive, robust features empowered 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:08:55] And we're back! I was thinking on the break back to my episode with Janine, which I hope you had as much fun listening to as we had recording it. There's an idea from that that I find myself returning to. It might be several ideas, I'm not entirely sure. One of the ideas that struck a lingering note with me is the fact that, as tech writers, we're constantly learning. That constant learning, having to update our skills, learn new tools, whatever it might be, that keeps us humble, and it also keeps us closer to a new user's or a new hire's mindset. The reason I think I keep returning to this has something to do with the idea of feeling not technical enough. I suspect that there's a superpower here, but it's hidden underneath the wrong narrative, and I want to unpack that a little bit so indulge me. One of the weird things about becoming a subject matter expert in anything is that you end up taking a certain amount of that knowledge for granted. You forget what it's like to not know some of those core building blocks. It becomes so familiar that it's almost an unconscious thing. You might call it unconscious competence. On one hand, this is part of the dread people sometimes express about asking an expert for advice or to answer a question. We don't want to look stupid in front of that person, and we often have to ask them to explain some of the things they assume we'll know. I'd like to suggest that this is, in part, also a tech writing superpower. The journey that we undertake every time we have to learn a new tool or domain or role or process, is also the journey that our readers are coming to the docs for. Because we are ourselves continuously forced into this role of not knowing and starting from scratch, it makes it a little easier for us to write for others who are also in this role. We are closer to that experience, so it's easier for us to put ourselves in that headspace to write from.

Kate Mueller: [00:10:57] It goes deeper than that. They're coming to our docs because they don't know. They're entering our docs searching for an answer for any number of reasons. Curiosity, frustration, someone else asked and they didn't know how to answer, whatever. We want to provide them with the answer so that they can get back to what they were trying to do and be successful. Whether that's a new hire wanting to know how to submit a request for paid time off, or a customer trying to figure out how to solve a problem with our product, or a developer trying to figure out how to build the integration that just got dropped into their lap. We want them to leave our docs victorious. A big part of their success, ultimately, is how well we can anticipate their needs to provide them what they need to answer the question. Sure, that's partially about knowing your user. What knowledge they come in with, what terminology they'll understand. It's also about remaining empathetic to the motivations that sent them here. I remember a Write the Docs talk, the presenter said that we need to recognize that coming to the docs is an admission of failure. That someone couldn't figure something out on their own, or by the in-app copy, and that we needed to recognize they were already coming to the docs with that sense of failure hanging over them. They were probably a bit impatient or irritated, and part of our job was to help them quickly get what they needed to be successful in spite of that failure or irritation.

Kate Mueller: [00:12:40] For some reason, reflecting on my chat with Janine, this line keeps popping back into my head. I still think the sentiment is accurate for product or support documentation, but I also wonder about the wording choice. Is it a failure when we ourselves don't know something and have to learn it so that we can teach it to others? Or is it just an admission of not knowing? If you're doing product documentation, you probably do think of it as a failure of the product that someone needs docs to figure it out. Or if you're doing internal documentation, you might think of it as a failure of the onboarding process or a manager that someone doesn't know the answer to this question already. I suspect that the voice that tells us 'this is a failure' is also the same voice that tells us that 'we aren't technical enough'. In this sense, Janine's suggestion to reframe it as 'I don't know how to do this yet', is also a fantastic mantra to keep in mind as we try to center our readers' experiences. They don't know how to do this yet, either. They're coming to the docs because they don't know how to do this yet. Our job is to try to help them know how to do it, so that they can move on to the next thing. We don't judge them for not knowing, we assume not knowing as a starting place, and we build our docs from that assumption. We center empathy, basically.

Kate Mueller: [00:14:08] That practice, totally, is a superpower in our docs, but it's a superpower we need to use more in the opposite direction too, for ourselves. When I first started practicing meditation years and years ago, one of the instructions I received was to pay attention to the way I talked to myself. Once I did, I quickly realized that I was much harsher with myself than I was with literally anyone else. Strangers, close friends, loved ones, coworkers. I had way higher expectations, the narrative I used for myself was so much more critical. Once I started realizing that this was a pattern, I was able to start noticing my own tone as I was talking to myself. I began to pause and say to myself, how would you say this differently if you were talking to a close friend? It became so much easier to approach myself with empathy and kindness. We often treat our readers or users with empathy and kindness, but we don't always treat ourselves that way. The criticism that 'we aren't technical enough' is never a criticism that we would throw at a reader or a user, but we use it so quickly with ourselves. We assume that we should somehow magically know. The next time you're feeling frustrated with yourself for not knowing more, or not being technical enough, I want you to notice that. Then I want you to pause and say to yourself, how would I say this differently if I were writing it in a doc? I'm guessing you'd be a bit more empathetic, maybe a little bit less harsh or judgmental. Probably a lot more focused on helping yourself learn what you need to learn to get from that place of not knowing to knowing. Try it, let me know how it goes.

Kate Mueller: [00:16:16] The Not-Boring Tech Writer is produced by the lovely humans at Astronomic Audio with editing by Dillon, transcription by Alan and post-production by Been and Alex. Chad Timblin is our podcast head of operations. Our theme song is by Bright Side Studio. Our artwork is by Bill Netherlands. You can check out KnowledgeOwl's products at knowledgeowl.com. 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.