Latest / The Not-Boring Tech Writer / Kate sounds off on “good” documentation
Transcript
- Kate 0: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. Kate 0:20 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 July, right after we launched the merch store for The Not-Boring Tech Writer. If you've been impatient to proclaim your not-boring status to the world. Check out the merch tab on thenotboringtechwriter.com, and that'll take you to our T public storefront for shirts, stickers, mugs and more. So get all your swag. I was so excited about it. All right, first, my progress update. Since my last solo episode about two months ago, I've updated another 43 articles, taking my grand total to 550. My velocity has been slower these last couple months, because I had to navigate a lot of personal things. In May, almost as soon as I got back from Write the Docs Portland, my beloved dog Zola took a turn for the worst, and by the end of May, we were saying goodbye to her. To be honest, I've been plowing most of my energy into this podcast and some of KnowledgeOwl's Owlcademy offerings. And for whatever reason, I really couldn't focus on docs in a way that felt good for a while. I spent a couple days on low hanging Doc's fruit, basically to get back into the swing of things. And it's only really been in the last week or two that I've felt confident tackling more substantive things. Kate 1:55 To make things even more fun, I accidentally also decided that it was the right time to tackle updating our contextual help widget feature documentation. I think initially I picked this because the UI related changes here were really minimal. The only significant change we had was a change in the top navigation menu. And so I think I thought that this was going to be a quick win, but I apparently totally blacked out the fact that I have been dreading reorganizing this content for at least a year. It ranks right up there with the search docs in terms of how much I was looking forward to it, and I just forgot about that until I started making the nav updates, and then suddenly I remembered it, and I was like, Oh, well, I'm already here. I started it. I gotta finish it. Let's just say that former me made some interesting decisions in these docs, and I know that they were the best decisions I could make at the time, but revisiting them now with fresh eyes, especially having done some diataxis inspired content type work to help me reorganize stuff, boy do I see them in a different light. But thankfully, the content type work has really helped me make some good organizational decisions here. Right now, at the time of this recording, I'm only about halfway through, but I'm already a lot happier with how things are organized and how those docs are feeling, and it feels really good to have done some of these big updates. Kate 3:37 The other thing I've been working on is actually a little bit of new feature documentation. KnowledgeOwl is testing its own AI chat bot in my support KB, and so I got to meet with our CTO to do deep knowledge transfer and learn all the ins and outs of how we built it so that I could start drafting the final feature documentation. At the time of this recording, that feature isn't live yet. Maybe it will be by the time we go to air. So none of that documentation is live into the world yet, but I'm still feeling pretty good about all the prep work I've done. Kate 4:15 One other set of updates- during the break from my solo episodes, I determined that my mouse problem was not completely solved. I have now taken significantly more involved and much stronger precautions, and I have trapped and relocated seven more mice, and this time I relocated them three times further away from the house than before, so they're onto a different island from where we live. So they're really not coming back at this point. As of this recording, knock on wood. I've now gone over a week without finding a mouse in the traps or any signs of them, and so I'm kind of keeping my fingers crossed that this is the very last time you will hear me talk about mice on this podcast. Kate 5:03 So there's all the work updates. And as usual, I've also been reflecting a bit on our most recent episodes. In this case, two episodes, because I didn't do a solo episode there. So I'm thinking a lot about Nick and Liz's episodes right now. Nick and I both share kind of a partial villain origin story from our deep, abiding love for Lego documentation, and I never thought to trace this as part of my own origin story. But as soon as Nick said it, I realized it was. My joy with Lego as a kid was really just a tech writing love story, right? I loved the structure of the instructions and the fact that they took me completely from point A to point B, and I built exactly what they said I'd build, generally with no words. But it's been a reminder to me that sometimes the most opinionated docs, the ones that take a very clear, definitive approach to the best way to do something, even if there are a whole bunch of other ways you can do it, that that really opinionated, prescriptive approach can be the most comforting for a reader. Kate 6:22 I had a similar experience of being really comforted by good documentation with a totally different type of technical writing recently. So I've been meaning- I like to cycle. I'm a road cyclist, not a mountain biker, and I've been meaning to order a new pair of cycling shoes for years, pretty much, but it's a really intimidating process for me because I have very rectangular feet for my foot size. I have a very wide toe box, and pretty much all of my toes are the same length. And a lot of cycling shoes are really narrow and kind of heavily curved at the ends, so I've always had to size up pretty significantly to try to get my feet to fit in the shoes. And I typically also always, for this reason, have to try shoes on in person. And the last time that I, you know, talked to somebody at my local bike shop about it, they suggested that I try shoes by a company called Bond cycling because they're typically, you know, kind of made better for boxier shaped feet. And I decided that this year was finally the year I was going to pull the trigger on that. So I went on their website to try to find where I could go try these shoes on, and I could not find any shops within a two hour travel time from me that sold them. And so I found myself faced with the most dreaded thing of all for me, which is trying to order cycling shoes online without trying them on in person. For me, ordering shoes online is a complete disaster if I've not tried them on in person. And so I was approaching this with a healthy amount of skepticism and a whole lot of dread. But I discovered something kind of awesome. Bond actually has what I would call really good resources for ordering shoes online. I'll link to this in the show notes, in case you want to go check it out, or in case you're a cyclist and you want to go check it out, but they provide a three page printable sizing chart with instructions on measuring your feet to get the best fit possible. And I know that printable sizing charts are a pretty common thing, but bear with me, this is a really good example of documentation. So here's kind of how the package works. They give you three pages, one for each foot, so you are actually measuring both feet. You're not just picking the biggest foot and using that, and then they give you a chart to convert your measurements to sizes, and each of the two foot measuring pages includes what they call a scale check. So it's a little section separate from the little footprint and measuring section itself. It's actually part of the instructions that you can put a ruler or measuring tape up to to verify that your page printed correctly to scale, so that all of the measurements are accurate. And although they told me the settings to use on my printer, this was a thing that might have given me a little bit of pause, and I had just that extra little bit of confidence that what I was measuring was actually correct measurements, just from that little scale check. I don't know who thought to put it in, but it was brilliant. And then included with the scale check, they have detailed step by step instructions on how to take the measurement. There's the three millimeter black bar, kind of in the lower corner, and you're supposed to fold to only show that black bar, and that goes against the wall. And then your heel goes against the wall, and you put your foot down in a particular way and shift your weight. And then you mark the longest point and the widest point on your feet. And then you use those measurements. And so you feed the measurements from that into the chart on the third page to try to decide your sizing. And what I really liked about this approach was that instead of just having- you measure this long and the diagram itself tells you what size you should order, they give you a much more detailed breakdown in the chart to show the ranges of the measurements that apply for a given size. So I felt like I could make a much more informed decision about what I ordered. For example, my width measurement was basically just below the cutoff between standard width range and wide width range, and knowing my feet and the nerve problems that I have in my feet, I decided to size up into the wide even though technically, my measurement didn't require that, and that actually proved to be the right choice for me. And the length stuff works the same. They gave me ranges, and that allowed me to figure out, ooh, if I want a little bit of extra space in the toe box, I could size up, and that's what this would look like. And my shoes, I did this whole process, I took my measurements, I ordered my shoes. The shoes arrived last week, and I've tried some trial rides, and I think, had I picked the out of the box, length and width, the shoes might have been a little too small, but because I had that range of measurements in the chart, and I felt very confident in the measurements I'd taken, I made decisions to size up just a tiny bit, and they fit me really well, and I did not have all of the initial nerve pain that I was kind of dreading and expecting and out of the gate, these fit me better already than cycling shoes that I've bought in person. So it's already a really good experience. Because of this little three page documentation that had thoughtful details, and then the way that that empowered me as a customer to make informed decisions, and very well informed decisions, I had a really good experience, which has left me with really positive feelings about them as a company. I wasn't left with the feeling like they were just trying to get me to buy shoes, but that they actually cared about whether those shoes fit me and therefore whether I had a good experience wearing them, and it just felt like the perfect example of something I like to tell people all the time, which is that good documentation is your product experience, and so far, I have had a really solid product experience with them, because that documentation was so good that I also ended up getting exactly the product that I wanted. That's a win for them, and it's a win for me. Kate 13:17 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 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 13:40 My favorite line from Liz's episode was the permaculture concept she shared: "the best fertilizer is the gardener's shadow". As she explained it during the episode, this is as much about the mere act of showing up.In the last few weeks of struggling to find the focus to work on documentation, I've used this a bit like a mantra, to just show up and do the work and not make it a really big thing in my head. Low hanging docs fruit tasks are maybe not the sexiest or the most exciting of changes to make, but every single one of those changes did still incrementally move my docs forward and the experience of my docs forward. If nothing else, it also helped clear away a bunch of mental clutter I had about how behind I was, so good documentation is your product experience, but it can also be documentation that's always improving. It's dynamic, it's iterative, it's always moving forward. Try to provide that best experience possible. As I've thought about Liz's quote more, I believe that there's a second layer to her observation, what I'm going to call the idea of care. If it was about just anyone showing up, it would be more generic, like the best fertilizer is shade, or the best fertilizer is someone's shadow. But we're specifically talking about the gardener's shadow, the caring individual's shadow, the person with a little bit of knowledge and expertise shadow. In tech writing, care and attention underlie so much of the work we do. Kate 15:33 Both of these ideas came full circle for me recently. In a completely non documentation project, I recently decided to use some scrap lumber. I had to throw together a little bench for the inside entryway of our house. We have a small entryway with some coat hooks where we take off or put on shoes and hang up our coats. Since we moved into this house in 2020, my partner has wanted a nice little place to sit there. It's a small space. So for a while, we were using a five gallon bucket with a little folded blanket on top. Then we moved to a big plastic tote bin, just for the record, neither of those were very comfortable. They just kind of served the purpose. Every time I thought about building a bench, I got hung up on wanting to include shoe storage under it, maybe some kind of metal rack, or some like metal rods or pipes or something, so that the wet shoes could dry really quickly and it would be easy to wipe off and maybe a little bit more maintainable than wood would have been. Each time I considered building the bench, I wanted to think more about that problem and how to best solve it before I built the bench. As we all know, what that really means is that I never started building the bench. I lost sight of the problem I was trying to solve. The original problem I needed to solve was the awkward seat, not shoe storage. In the same way that sometimes we think, Oh, I just need to do these UI updates to my Docs, and in the process, I must also reorganize and bring up the style guide and blah, blah, blah, blah, blah. This is the story of my life, apparently. Recently, I was like, okay, I need a project. I need a physical project. Let me actually suck it up and build a bench. I started looking at some benches online, and I realized at that moment that I was over complicating the solution. Lots of people make wooden benches that either have no shoe storage or don't have any drainage, or they're just like wooden boxes, basically that people sit on. Kate 17:55 I needed my bench to fit in a small space. It's not like I could put a ton of shoe storage in there, anyway. I decided to build a pretty simple little bench. I took measurements of the space I had, then I dug through my scrap pile, and I ended up building it out of some scrap maple plywood and some stock two by fours and four by fours. I did manage to include a small amount of shoe storage, just like three little planks with a wide gap between them for drying shoes. It's enough to fit two pairs of shoes, but it also fits in the space. The amazing thing here, and maybe part of why I'm talking about it, is that I was able to complete the design, measuring, cutting and assembly in one weekend afternoon. It was five and a half years of waiting for a thing that I could throw together in an afternoon, once I gave myself permission to only focus on the problem I had to solve and to recognize that it didn't have to be perfect. We started using it right away later that day, and about a week later, I got the stain on it, and I keep hoping for the right weather so I can cover the shoe storage area with a good sealant, but we've been functionally using it every day since then. Is it the prettiest thing I've ever built? Oh goodness, no, definitely not. This is a wildly flawed bench from a distance. It looks great if you look at it up close. It is not my finest work, but it's also not the ugliest thing I've ever built, and it definitely solves the problem that it needed to solve, and very usefully, it let me test a bunch of theories about how I thought the bench should be constructed. Kate 19:44 Because of that, if I build another one, when I build another one five and a half years from now, when I build another bench, I'll approach some of the legs and the cross pieces differently. I think I might do some of those connections very differently, and I have a better feel now for just how much space proper shoe storage would take up. I know that I can't do it in the space that I have. But right now, you know, it's great. We have a bench to sit on, and it stores two pairs of shoes perfectly, one for each of us. And my partner has already complimented me on the height that it is. It's the perfect height for sitting on it. It's actually quite comfortable. You can set stuff down on it when you first get into the house, and it is a monumental improvement over the five gallon bucket and the plastic tote that we were using before, which has been just such a good reminder that sometimes just showing up and working with care can produce 80% of what you need. Would it be nice to have that other 20%? Sure, but you often don't need it, or by doing that first 80% you'll learn that part of your approach is wrong. Isn't it better to have made that series of errors with scrap wood than with a really nice, high quality wood that I'd paid good money for? Just the reminder that an MVP is always super helpful. This next month, as I'm juggling a lot of emotionally heavy things and a big backlog of work and maybe still trapping mice, who knows, I'm trying to focus on the things where just showing up with a small amount of care and thoughtfulness can yield results. My widget documentation might not be perfect when I'm done. No, I know it won't be perfect when I'm done, but it will be significantly improved, and that's going to feel amazing. So for this next month, I hope that you and I both can find some documentation where our tech writers' shadow can fertilize some good content updates and recognize that you don't have to design or do the whole thing all at once. 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 have just been dying to hear me, sound off on some particular topic, please message us on LinkedIn, or Bluesky at The Not-Boring Tech Writer. Or email us at tnbtw@knowledgeowl.com. Kate 22:33 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 Bright Side 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 that's knowledge with S, A, S, S.com, until next time, I'm Kate Mueller and you are the not-boring tech writer.