Latest / The Not-Boring Tech Writer / Kate sounds off on lovable docs
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 March, actually right before Pi Day, in the constant roller coaster that is spring in New England, which means that in the last week I've seen snow, fog, rain, high winds, sleet, highs below freezing, and highs above 50°F, and some delicious sun. Not nearly enough delicious sun, but we're getting there. [00:01:03] First, my progress update. Since my last episode, I've gotten to spend some lovely time back in the KnowledgeOwl Support knowledge base. I've worked on documentation for a brand new KnowledgeOwl API that's designed to help export data from Owl Analytics so it can be used in things like business intelligence tools, data visualizations, dashboards, and all that fun stuff. I've always iterated on existing API docs before, so this is my first time drafting API docs from scratch. This has actually been a really great “baby's first API docs” experience, because the Export API currently only has one endpoint, so it hasn't been overly complicated. Kate Mueller : [00:01:46] In the process of doing this, I've learned some new tricks that I'll probably apply in our main API documentation, so it's been a useful learning experience that way as well. I'm almost done with a forkable Postman collection for the endpoint as well, just as a nice little one-stop-shop option for our customers. Last month, we also added a new HubSpot importer and a generic CSV importer. As part of that, we changed the layout and interface of the import tools. I did some docs updates for those UI changes, and I wrote new docs for the new import options. Looming very big on the horizon, our CTO, Pete, has been working on a complete redesign of the KnowledgeOwl article editor, which is the core of our app. I will have a truly massive amount of text and screenshot updates to make once those changes are ready. I'm really excited for the changes, so I'm hoping that that excitement helps me power through those updates. It will be quite a bit of work, but I think it's going to be a much better user experience, and for that, I'm really excited. I'm also helping with a little bit of the app microcopy there, so I'm hoping that I can find ways to be succinct but also helpful. [00:03:06] My change management toolkit is more or less done, it's just not released yet. We'll be releasing a very detailed KnowledgeOwl-specific version to our customers, so if you are a customer and you're listening, keep an eye out for that. Once that launches, I will create a more streamlined, less specific version that we will share with non-customers. Once that second version is complete, I'll share the access details with you here on the podcast, and I'll probably do a more in-depth walkthrough in a solo episode, since that's been quite the project, and maybe there's some useful learnings there that you could apply to something that you're doing as well. [00:03:47] I've also been reflecting a lot on my interview with Jacob Moses, who was the original host of this podcast. He was a delight to have on. Jacob, if you're listening: thank you. Shout out to you for being so generous with your time and your energy. Our conversation was far ranging, and I'll be honest, it left me with so much to chew on. One of my big key takeaways was how much the skills and strengths Jacob cultivated as a tech writer have served him well in his real estate development work. This is one of those questions I feel like is floating around in the ether for a lot of us, given some of the uncertainty in the job market right now. Will my skills transfer somewhere else? Can I market them to pivot into another role or industry? I think some of Jacob's examples do make it clear that, yes, those skills are transferable. They will be useful. They just might not be the thing that will explicitly land you the job, but they'll be a definite bonus to have in your toolkit, so to speak. I love that he's created some documentation for his tenant and client onboarding and troubleshooting. I've rented a lot of places and I don't think I've ever had a landlord do that for me beyond just giving me a number to call or an email address to send to or some usually pretty crappy work order request form. I've definitely never had a landlord give me immediate troubleshooting steps for common issues, so I totally loved that one. [00:05:18] And I appreciate that his decisions about what documentation to create were driven by what's basically a just-in-time documentation approach. He's written only the stuff that felt like it was needed when it felt like it was needed and iterated on that, rather than crafting some giant tenant handbook. If you want to dig deeper into just-in-time docs, just as a mindset, Jacob did a very early episode with Bri Hillmer on this topic. I think it was season one, episode three, and I'll link to that in the show notes in case you want to take a dive back into the past. [00:05:57] It's clear from listening to him that thinking about the end user experience, in this case, end users being his tenants or clients, has driven a lot of the choices that he's made. He credits some of his interviews on this podcast, as well as his time writing technical documentation, as helping him to center the user, and the care he's putting into designing thoughtful systems for his current work seemed pretty evident to me. That ability to center the user, I think, is applicable across industries, across roles, is one of those things we all should be showcasing, particularly if we're trying to pivot out of tech writing. For those folks who are trying to get into tech writing, being able to demonstrate that you have that awareness and ability could be really useful. Jacob pairs that end user experience with the practice of humility, of letting the user experience drive some of the ways that Care Block works. One of the examples he gave me has really stuck with me. It's when he was talking about accommodations for vision and mobility impairments. Care Block now has experience with installing fixtures and furnishings to help address those impairments, and I really liked that Jacob mentioned that and then said that ultimately it's the end user who's the expert. We can present those options, but really, we rely on our clients to provide feedback on what they feel they need, what they feel will or won't work for them. They're the experts, we're just trying to do our best. This stood out to me in part because right after it, he said that it can take a while to get there and to never judge, or to have preconceived notions of what care and support look like. Kate Mueller : [00:07:45] I think that's a good rule of thumb for a lot of work, including technical writing. It can take a while to find the right solution, and if we approach the process with preconceived notions of what the solution looks like or should look like, or we limit our options on what the solution should look like, we sometimes shut down really important conversations with the people whose lives are going to be impacted by the work we do. We need to build the documentation that our readers need, not necessarily the documentation we're most comfortable with or familiar with building. [00:08:22] You know how much I love a good metaphor. I'm a metaphor girl. This is probably super clear from all these solo episodes. The thing I've been coming back to a whole lot is the idea of extending the concept of neighborhood to our documentation. I know this might seem a little out of left field, but bear with me. Here are five ideas that came up in my discussion with Jacob around neighborhoods and community development that I believe tie really nicely to documentation, or I'm at least going to make the case that they do. So here, in no particular order. First, you don't necessarily have to plow a lot of resources into big changes to have a big impact on your reader experience. This came up from Jacob in a couple of different ways. One of his big learnings was that it doesn't take a lot for people to have a good time in a neighborhood. You don't have to build a bunch of stuff, specialty spaces, whatever. You just have to make the space available or let people know it's fine for them to use their front yards or their front porches for stuff, and that freed up some of Care Block’s resources to focus on other things. He also noted that small improvements can make a big difference. I'm going to quote him directly there: “It doesn't take much to paint a crosswalk, to install a streetlight, little traffic calming interventions. Stuff that actually translates to a better user experience.” [00:09:54] It also doesn't take a lot for people to find value from your documentation. You might not need to complete coverage or a massive overhaul. Instead, spend some time trying to understand what your reader's biggest pain points are and where your improvements would do the most good, and then make those small improvements and see what happens. [00:10:16] Second, have conversations–or at least bear witness to conversations–where your readers are most comfortable having those conversations. Jacob tied this to Doctor Elinor Ostrom's concept of cheap talk, which I did a little research on after our episode. Ostrom is actually a Nobel Prize winner. She works in the intersection of economics and game theory. The cheap talk concept really contradicts a lot of the old “tragedy of the commons” mentality. “Tragedy of the commons” very loosely is when nobody owns a thing, everybody feels fine abusing or exploiting that, and the idea that government or institutions have to step in to oversee the effective usage of that commons. Ostrom's work, particularly around cheap talk, shows that sometimes you actually don't need a lot of government or institutional oversight if you let people speak naturally and with each other to make decisions about those common resources. All the folks involved, if they have a way to participate and to establish those social norms around how the commons will be used, sometimes you don't need that legislative oversight as well. While documentation isn't necessarily a public commons, the underlying idea of paying attention to that cheap talk wherever it occurs seems valuable to me. [00:11:53] These conversations might be in your help ticketing system, in your Discord community, in transcripts from sales calls, in Reddit or subreddit threads, analysis of customer interviews, whatever you have available, but getting those authentic conversations…oh man. So gold, so gold. Even if they aren't explicitly discussing your documentation or your product, you want to hear how your readers talk about the struggles they face and the things they hope to achieve. That helps you build documentation that speaks more authentically to those concerns and will in turn, create a more lovable space for your readers. Because they'll feel seen. They'll feel heard. They'll feel like you understand them. [00:12:44] Third, don't just copy and paste best practices or templates from other places. Use them as starting points. Figure out what jives with your docs and what doesn't, and iterate as you go. Jacob brought this up in the context of zoning ordinances or bylaws, where people will attend a conference, and then they'll copy and paste those ordinances or bylaws that seem to work from somewhere else into their municipality. I think it's equally applicable to documentation. General best practices or sample templates are just that. They're general. They're a great place to begin when you have nothing, but you'll get the most value from them if you refine them until they fit your use case. [00:13:27] Fourth, incorporate documentation into your onboarding. Shock of shocks that I'm suggesting this. Care Block does this with the laminated cards with QR codes that they give to tenants to streamline common questions or work order processes. In our case, make sure your documentation is incorporated into both your reader and your new hire onboarding so people know it exists. And it's even better if, however that incorporation happens, that it's taking people to a streamlined experience directly structured to help them get value out of your documentation the first time they engage with it. So in Jacob's case, those QR codes open a very specific individual document that has checklist steps or other guidance in it. You could do something like this for the onboarding, where you're giving folks a getting started checklist or some kind of orientation. [00:14:25] And fifth, support readers who have differing levels of engagement styles. Care Block has created multiple avenues for tenant and client engagement, ranging from direct emails, direct phone calls or texts, to app-based interactions for work orders or scoping work, to block parties where they just socialize. Their tenants can choose which forms they're comfortable engaging with, and that choice gives them agency. They can self-select the stuff that feels most important. Make it easy for people who know what they want–such as how to complete a specific task–to find and use your documentation, but also provide more detailed tutorials or explanatory content for the newbies who need more support, or for the folks who like to deep dive to really understand how things work. Recognize that you're going to have some readers who are going to be purely transactional in nature, and then you're going to have some readers who need more than that, and make sure that you have content that's addressing all of that. This is where getting back to some of the Diátaxis models or the Seven-Action framework from Fabrizio. Any of those would be really useful here. [00:15:46] 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. [00:16:09] I really love when podcast interviews throw me a little bit of a curveball, and Jacob's interview definitely did that, but in a somewhat unusual way in that we happened upon a topic that had a really surprising sense of synchronicity. That's the idea of lovability. Lovable neighborhoods and lovable buildings are a core piece of Care Block's philosophy, which I didn't know heading into my interview with Jacob. I had also had lovability on my mind lately and I can trace the root of this. I read a ten-year-old blog post by Henrik Kniberg called “Making Sense of Minimum Viable Product, and why I prefer Earliest Testable, Usable, Lovable.” I'll link to the post in the show notes in case you want to go down this rabbit hole, but basically, Kniberg encourages a mindset shift in a couple key ways. First, he gets rid of the idea of “minimum,” which is definitely not something most of us want, and focuses on earliest, since who doesn't love to get good stuff a little early? It's like when you get to open a Christmas present the night before you open the rest of them. It's a little exciting, right? [00:17:23] Second, he throws out the word “viable” because it's vague, also it's one of those words that even different people on the same team often define differently, and he focuses instead on three release phases: Earliest testable, which is the first release that customers can actually do something with, but it's largely designed to generate feedback and as a fact finding to figure out what customers really need to learn from the experience. Earliest usable, which is the first release that early adopters will willingly use. It still probably doesn't fully solve their problem, but it has enough meat on its bones to be usable for the task at hand. And then Earliest lovable, which is the first release that customers will love, tell their friends about, and be willing to pay for. Ever since I read this post a few months ago, and it's probably been six months, it's been sitting in the back of my head for a long time. I keep coming back to the idea of lovability and how it might apply to technical documentation, because let's face it, a lot of people don't consider technical documentation to be lovable. It's sometimes seen as a necessary evil or a cost sink, or a way to compensate for subpar or unfinished UI. Even when it's seen as your product or an extension of your product, it's usually not considered the lovable part, it's just an add-on. I believe technical documentation can be lovable, and that's an idea I've been trying to explore further. [00:19:03] I'll admit, my ideas on this are not necessarily super well-formed. This might be the most woo woo I ever sound, so apologies in advance. If that's the case, you're welcome to tap out. Maybe it's a spicy take, I don't know. Maybe it's just Kate being really weird. I guess we'll find out. My first premise in thinking about this is that documentation can be one of the most lovable parts of your product or company. When I say this, I don't necessarily mean that every single page of your documentation is going to be the most lovable part of your product or company. I'm thinking more of documentation that readers really connect with, like a really good conceptual overview or explanation that demystifies a complicated thing, or a tutorial that really and truly walks a new customer through how to understand key concepts and see the value of your product, or really good onboarding documentation for your new hires so they can start feeling competent and contribute soon, or at least sooner rather than later, or even a thoughtful code cookbook that gives detailed and applicable examples to developers. These can be truly lovable interactions, and they’re not necessarily, it's not a transactional interaction. Those interactions can set your product apart from your competitors, or make new employees feel like they're seen, respected, and supported. [00:20:43] I'm reminded of our recent episode with Kelton Noyes, season three, episode 28. He shared that he took a new hire training time of three weeks, plus a three-month ramp up period. Thanks to overhauling the documentation, he reduced that time period to two weeks total. That's about 14 weeks less of that uncertain, frustrated, awkward, mildly incompetent feeling we've all experienced when we've started a new role. And what is that, if not a bit of love extended to your new hires? [00:21:23] In thinking about this, from this premise, that documentation can be one of the most lovable parts of your product or company, here's my first suggestion for making lovable docs: identify ways that readers will feel loved by your documentation and focus your efforts there. What does that even mean, that readers will feel loved by your documentation? This is the woo woo part. I warned you. Based on my conversation with Jacob, I'd say it's anywhere that they feel cared for and supported by the documentation. So where do your readers need the most care and support? You'll have to answer that for yourself, but I have some ideas. For internal documentation, new hire onboarding materials, or info on how to get set up with a new piece of software, or the process they have to follow to request access to said thing, those might be really good choices. Maybe less obvious could be things like a really good history of why something is built the way it is, or a reference page that's never existed that could help demystify stuff that a lot of your new hires ask questions about. Any of those could qualify as a place that your readers need care and support. Kate Mueller : [00:22:41] For product or support documentation, this is going to sound like a broken record, but target the biggest pain points or the most confusing user interface elements. Talk to your support team or your product team and find the features that your customers struggle with the most so you can clarify them, but also find the features that customers naturally seem to love the best. You can showcase them, because if you can drive them into the pieces of your product or organization that your longtime customers most love, you might increase the connection that they have, and then they'll have a little bit more mental bandwidth to tackle the stuff that's a little bit more confusing. [00:23:27] My second premise about lovable docs, and I'm just stealing directly from Jacob (imitation is the sincerest form of flattery, after all), it's the idea of reciprocity. He said, "If you build a lovable place, it will be loved in return by whomever you're leasing the home to." And in his case at Care Block, the love and care that they've put into the buildings that they've rehabbed and that they rent out has translated into tenants, on some level, noticing that care and attention and feeding it back into the homes that they lease, which causes them to take better care of the property. Documentation that centers care and support can similarly prompt your readers to treat your documentation with care and support. In this, I have to admit, I'm a little bit lucky because many of my Support KB readers are writers themselves, so I've had customers open tickets to point out typos or to debate a style choice I've made. I'm sure some people view this type of feedback as negative, but I see it as talented technical writers showing me they love my docs by pointing out things that are wrong with my docs, by pointing out places that they think are creating friction for folks. When readers report something odd with a particular page, or they submit a pull request to improve it, that's an expression of care and attention. You have to give a shit about something to take the time to do that. [00:25:05] And so from this, I'm going to come up with my second suggestion for making lovable docs, which is to build docs you love. Not docs you tolerate, not docs you feel are good enough. I'm not even going to mention the idea of done, because we all know that's elusive and never going to happen. They're certainly not going to be perfect, but you don't have to be any of those things to be lovable. I can love a document even if it's incomplete or it's not quite done. I can love it even if I whipped it up as a band-aid because a band-aid is still an act of care for an underlying cut. I know from long experience that no matter how amazing I think a document I've written is today, when I return to that same document in a month or six or twelve, I will find a ton of things I can do to improve it. But that doesn't make it unloveable now. I can love it and be proud of it while still recognizing it needs improvement. If I think about the docs I've felt I loved the most, oh my god, that's a weird sentence to say out loud, but we're doing it. So if I think about the docs I felt I loved the most, they have a few traits in common. They have a clear purpose, they serve an explicit need, they're well-focused and well-scoped, and their mere existence makes life better for the people using them. They clearly define key concepts that new readers might be unfamiliar with. They solve a problem. I want my documentation to be a safe space for my readers, for them to know that once they enter this space, they're treated with respect and support, no matter how well they know our product or don't, no matter how well they know the terminology we use or don't, no matter how technically adept they are or aren't. Creating that safe space means I have to recognize my responsibility in creating and maintaining it. It means approaching the task with both hope and humility. It means thinking about the actual people whose workdays and therefore whose actual days might be improved by the experience of using my docs. Kate Mueller : [00:27:22] Since I had the lovely experience of coming up on the support side here, I can very easily picture a few of my closest customers when I work on docs, so I can imagine Sarah or Sandi or Scot's experience when they reference what I'm writing. It's not that I'm explicitly writing for a user persona, but I am centering the human at the other end and thinking about how I can make their day a little bit better. Yes, I know these days it's as likely to be an AI agent on the other end as a human, but I will always write first and foremost for other humans. Lovable docs probably look different for each of us depending on the type of documentation and our audience, our documentation's purpose, how people access it, and a host of other variables I can't even think of right now, but I believe it's worth giving some thought to whether our readers could find our docs lovable, and if so, how we can deepen their lovability. That might mean consistency, it might mean appropriate graphics, but not too many, it might mean great code syntax highlighting or dynamic examples. You know your readers better than I do. Figure out what lovable docs means for you. It's an idea I'm really interested in. [00:28:44] If you have ideas about how to make docs more lovable, I would love to hear from you. Even if it's you being like, “Kate, this was the weirdest flipping episode I've ever heard you do. I'm concerned for you.” I'd like your feedback on this one. At any rate, this month I'm thinking a lot about how my documentation can serve as a neighborhood and how I can take some of Jacob's comments and apply them as a technical writer. If my documentation is a neighborhood, I want it to be an inclusive, welcoming one that's laid out in a way that's easy to get to what you want or need. I want all the crosswalks to be well-marked and maybe painted in fun, playful ways. I want all my street lights to work without overwhelming light pollution. I want clearly visible street signs everywhere so it's easy to get around. I want it to be clean and friendly, but not so predictable that it's boring. I want it to invite people to explore. So many of the best practices we talk about can help achieve these goals. Using consistent content types or templates, cross-referencing, using callouts and headings to form an easy-to-scan visual structure, keeping things maintained so there isn't a lot of noisy clutter in the way. But let's be conscious that what we're doing is building a neighborhood of knowledge. Neighborhoods grow and adapt based on their residents and needs and funding and a whole slew of other variables. Our documentation similarly needs to grow and adapt to make people feel welcome and to keep them coming back. Kate Mueller : [00:30:25] And thank you, my lovely listener, for coming back to another episode. I hope the neighborhood we're building here is welcoming and supportive to you, too. 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. [00:31:09] 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.