Latest / The Not-Boring Tech Writer / Kate sounds off on instructional design
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:28] 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 at the very end of August, right after the news of both Dolly Parton and Tim Curry's deaths. First, my progress update. Since my last solo episode, I've updated roughly 20 more articles relating to the article editor changes. The exciting piece of this is that I have now officially finished my minimum viable docs (MVD) list from the initial release just a little over four months later. I don't know whether to laugh or cry about this. We're choosing laughter. Always choose laughter. So at this point, that MVD list is done, and my secondary punchdown list of everything that didn't make that cut has about 50 articles in it. So hopefully in the next two months I finish that; however, that does not include the pages I need to go back and re-update due to other UI changes we've released since that first release. So yeah, I don't quite know my full punchdown at this point, but it is starting to feel like I can see the light at the end of the tunnel, months later. Kate Mueller: [00:01:42] I also spent a good chunk of this month overhauling our API endpoint documentation. We just released much more granular permissions for our API keys, and I wanted to update the API spec file to include those permissions. As it often does, this turned out to be quite the yak-shaving event. It began with researching adding permissions-related information to operations. When I realized that I needed to upgrade from OpenAPI version 2.something to version 3.something, and I have a confession to make: I finally started using AI this month specifically because of this project. So if you were thinking I was one of those last holdouts, I'm sorry to disappoint you. I have finally acquiesced. So here's kind of how that went down. I figured that I would miss some nuances in upgrading our OpenAPI version from 2 to 3, so I made the changes I thought I needed to, based on the bullet point list that OpenAPI itself provided. And then I asked Claude Code to evaluate my spec file against version 3.0. That evaluation did help me get onto version 3.0 really quickly. It identified some places that I had misunderstood either the original spec or the updated spec. Kate Mueller: [00:03:08] So not only did I get onto version 3.0 pretty quickly, but along the way, Claude Code also identified some redundant or unnecessary repetition of fields, and I was able to tidy up my spec file a bit. And then once I got to 3.0, I was like, might as well go to 3.1. So I used a similar process to upgrade from OpenAPI 3.0 to 3.1. And then I realized that I maybe needed to update Redoc. So I upgraded from version 2.1.3 to 2.5.3. Spoiler: they are working on version three, but I'm not waiting for that. I just wanted to get on the latest versions of all of the things. And of course, like all good gateway drug stories because Claude Code made this stuff way easier, I decided to push it a step further and explicitly asked Claude to evaluate a couple endpoints that had always felt awkwardly set up, mostly due to my own lack of detailed understanding of the OpenAPI spec. That gave me a couple alternate ways to handle use cases of certain things, and although I did get into arguments with Claude Code a couple times on solutions it suggested to me, ultimately, I did feel like I ended up with something pretty good. And since I was revamping everything anyway, I used this opportunity to invite Sue, one of our developers, to tell me the things that irritate her about other people's API documentation. Kate Mueller: [00:04:36] And one of the big pain points there was not being very explicit about the data model overall, among other things. And that set of pain points led me to make some other changes about how we order and describe things, not necessarily about spec adherence, but about usability. Along the way, I did run into some situations that I didn't trust Claude on. The biggest of these was cases where the model name no longer aligns with what we actually call the concept in the UI. I mean, I could have asked Claude about this, I did because I was just curious what Claude would say, but both Sue and I were like, let's not take Claude's word for that. Who knows if that's actually a best practice? So here's kind of the situation, let me give you an example. One of our models is called “agent” because when KnowledgeOwl was first built, it was going to be part of a help ticketing system. And so “agent” was the label picked, but now we are very much a standalone knowledge base product. And so we call our users authors, not agents. And there was a period of time where they were called users, so there are also some models that say user something or another, userroles, userteams, etc. So there are a few ways that the model names are not reflective of the current reality in the UI itself. Kate Mueller: [00:06:04] Historically, the API spec file has only ever used those model names, and generally it did not really heavily connect the model names to the current UI concepts. And this was the sticky widget for me. It was a question I really wanted expertise on, certifiable expertise. And so I reached out to Lorna Mitchell for some advice. So if you've been a diehard listener, you'll remember Lorna was my first interview when I took over hosting the podcast. So that was season three, episode two. So it's been a hot minute. But she's on OpenAPI’s technical steering committee. So I figured you can't get much more expertise on OpenAPI than that. And I knew she would be a wealth of information and she did not disappoint. So her big piece of advice for me was you can't break the contract you have with anybody who's consuming your spec file. Those models obviously have to be kept consistent at this point because it's not like I can go change them in the actual code base. The tags need to be kept consistent, but at least the URLs for the tags need to be kept consistent. But everywhere else, I should be using what we're actually using in the UI and then doing some explicit mapping there between what we're calling stuff in the UI and these outdated named models. There's a whole bunch more nuance to it, but that's kind of the TL;DR version of it. Kate Mueller: [00:07:33] And so I actually took her full feedback that she gave me, fed it into Claude Code, and asked it to create a list of changes based on her feedback, just for me to understand sort of structurally how I would go about addressing this within the OpenAPI spec. I also asked it to apply her suggestions to one of my models. Spoiler, I did not totally love its approach on all of that, but what it did for me was to help me get a feel for the nature of the changes I should be making. And so the biggest change in how we structure our spec file that came out of this was that I started using top-level tag definitions. [00:08:12] Previously, we had applied tags within operations, but we didn't have a top-level tag section. I honestly don't know when that top-level tag section got added in the spec. It might be it only came in in version 3.0, and my upgrading gave me the ability to do that, I don't know. I'm not an OpenAPI guru, but adding that top-level tag section opened up a lot of possibilities for me. It helped me organize the table of contents in the docs better, and that allowed me to assign a tag display name while not changing the underlying tag that shows up in the URL. So that allowed me to include the UI concept with the model name in parentheses, and add some links to documentation and other key concepts, which had always been tucked into operations and not at the top-level object level. [00:09:05] So I think what I've ended up with there is fairly accurate to Lorna's suggestions, but it also gave me much finer grained control over the presentation that I wanted. And those changes led to some really productive conversation between me and Sue because I was having her review as I went. I was like, "Hey, does this make the data model make more sense? What do you think about this?", and she happened to be the one who was working on the more detailed API key permissions. And so that turned into a really nice feedback loop in which she made some changes to the UI labels we're using in the API permissions screens because of the docs changes. And then in turn, I made some changes to the API docs based on her feedback. So it was a really excellent collaboration. And so in a weird way for me using Claude code here, it both helped remove a lot of the really time-consuming, tedious bits, but it also highlighted how important human collaboration is. I knew the things that I didn't really trust Claude's feedback on, and I ended up working with two very smart women who know a lot about APIs from different perspectives, who are much smarter about it than I am. Kate Mueller: [00:10:16] Then I was able to use Claude Code for some of the validation and automation of updating certain things. So I hope I have done justice to the feedback that both Lorna and Sue gave me. Ironically enough, I did all that work and got into it to upgrade to a more recent version of OpenAPI for the permissions-specific stuff, and then realized that a) I did not really like the presentation that Redoc gave me on those permissions, and b) I realized that I was hacking the standard because those permissions are supposed to apply to OAuth and we use Basic Auth. And I decided not to hack them, and so now I just have permissions in the description field. So as with all yak-shaving events, I did all this work to enable this feature, and then it turned out I didn't actually want to use the feature. Fun times. But what that did ultimately produce for me, aside from a much cleaner spec file, is it got me using Claude Code for things that were easy to validate against the specs themselves or the Redoc linter. And so that helped me make sure that I have valid YAML, for example, and valid to the OpenAPI spec, and valid syntax for the Redoc linter. And it allowed me to make some very fast, easy programmatic updates to a YAML file that's now over 5000 lines long, which has gotten me far more internal consistency within the spec file, but at a fraction of the time I would have had to spend on it previously. Kate Mueller: [00:11:50] And what that ultimately led to is that I created a Claude skill from my session to help me perform a series of quality control checks in the future, so that skill looks for valid YAML formatting, adherence to the OpenAPI spec, valid Redoc formatting, and enforcing a few style guide choices I made along the way, mostly because I discovered, well, Sue discovered I had some inconsistency and I was like, "Ugh, okay, let's write a rule for that. I don't ever want to run into that again." So it feels like I have kind of a unit test for my API spec file now, and that has always been one of those pieces I didn't feel confident in. Redoc was rendering what I was giving it, but it was not necessarily formatted in the best way for it. Sometimes I had invalid YAML that it was swallowing and just dealing with, and now I have actual valid YAML. And my plan is to use this skill every time I make substantive updates to make sure I haven't misformatted anything. And also, if I need to upgrade our version of OpenAPI or Redoc in the future, I'll repeat the processes I used this time around. Kate Mueller: [00:12:56] So that's a very long, deep dive into me finally drinking the AI Kool-Aid. Also, if you are working on OpenAPI spec files and you want a copy of my very simple Claude skill, drop us a note and I'll happily share it with you if it saves you a little bit of time. And of course, since I was in there while I was tinkering with Claude Code, I also used a connector one of my teammates built that lets me query the KnowledgeOwl code base. And I specifically had it identify cases where the API spec file is missing fields. Most of these are fields that have been added in the last couple of years, especially during a window where I was not actively maintaining the spec file. I thought I had caught most of these, but of course Claude Code found the ones I hadn't. And so I now have, I have a nice little punch down list of overlooked fields that I need to add. But y’all, I don't know. Dolly Parton died, Tim Curry died, and I am now using AI. I'm pretty sure this means the world has actually already ended and we're in some kind of weird fever dream. But if it's any consolation, although I am using AI, I'm still using it very skeptically and only for specific things in situations where I'm not having it write actual words because I kind of want to throw up a little saying that, but I am using it for things that can and probably should be automated where it's validating outputs against defined specs or against other things. Kate Mueller: [00:14:30] And that does save me a lot of work and energy and effort and makes me feel a lot more confident in the way that the docs are formatted and the output that they're going to produce. But I'm still relying on knowledgeable humans whose expertise I trust for finer nuances. So I haven't completely gone around the bend, I promise. Let's see. Aside from that very long tangent about AI, what else is going on? I did updates on all of our API key documentation because we were releasing the more detailed permissions for it, and all of that was prepped for the release, so we had a super smooth release and a really nice announcement about it. And what am I currently working on? I'm currently in the midst of helping with testing and docs on two upcoming releases. One of them is a new Teams app, and the other is a new file import tool. And of course, the new file import tool branch includes top navigation label changes, so I will have another large punchdown list to navigate around my article editor updates. And right now, I really don't want to do a blanket find and replace because I do want to review those items in context, but ask me how I feel about that in six weeks, and maybe I will have just done a blanket find and replace. Who knows? Kate Mueller: [00:15:55] Let's see. So I need to finish up some docs so that we can submit our Teams app to the Microsoft Store for approval or whatever it's called. And then hopefully we can check off another new integration for the year. I'm also planning for a few KnowledgeOwl webinars in the coming months, which should be a lot of fun, especially since it means I get to work more closely with Erica, who I haven't had a lot of daily interaction with for a while, so there's a lot of good, fun, exciting stuff on the horizon. Kate Mueller: [00:16:25] 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:16:48] And of course, I've also been reflecting on my interview with Katie Cox. Talk about burying the lede. One of my big takeaways from this conversation was just how much overlap there is between instructional design and technical writing. This was a thing I suspected before the interview, but the interview really drove it home for me. So both roles require you to be good at distilling something that might be very complicated into a simpler, understandable explanation. Both require you to work with subject matter experts to review content for accuracy. Both often require that you create some kind of metadocumentation, materials to help others contribute to your docs site or your learning management system. Both don't necessarily require formal education in the subject, but they do generally require portfolios and some explicit dot connecting when you're applying or interviewing, especially if you lack that formal education. And both do really need you to think very carefully about your end user and their goals and what you're hoping they take away from the experience. The big difference that kind of came out of my conversation with Katie is who those end users are and what their expectations are of your content. There is a difference between a reader and a learner. That's, I guess, how I would summarize this. If they're visiting your knowledge base or your docs site, most likely they're looking for quick answers to questions. They probably don't want to spend a ton of time there. More time on page doesn't necessarily mean that they're getting more value out of the content. It might actually be a sign that your content is difficult to navigate, or you're misleadingly labeling things, or who knows what. Kate Mueller: [00:18:34] But if they're visiting your academy, they probably aren't looking for a super quick answer. They're there to learn. That comes with an expectation of more time spent, and it changes the expectations for the content itself, since you in turn need to create content that both teaches them what they need and keeps them engaged. And since I'm working on webinars first, but ultimately hoping to develop proper learning modules in Owlcademy, a lot of the suggestions Katie shared are things I'll be coming back to, and things that I've been kind of marinating on. I loved how she stressed that you should leave room for your learners to self-direct their learning, because that's generally how adults learn best. Fun fact: when I was in grad school [mumbles] years ago, as part of my graduate assistantship, I did a literature review on self-directed learning, so I read key texts and articles from probably 30 or 40 years’ worth of study. So I do know a little bit about self-directed learning. And Katie's right. It is generally the best way for adults to truly, deeply learn a subject. So keeping that sense of agency and directing your own learning to pursue the paths that you want to pursue is pretty key. She also suggested that you should never put gates on the content that prevent someone from moving forward if they think they're ready to move forward, which was not a detail I had thought about. I just think about how annoying I think it is to have to click every single interaction on a page before I can move on to the next lesson. Kate Mueller: [00:20:13] And I liked that she stressed this despite the fact that many tools designed to help you create learning content encourage you to put gates on. Her phrase for this, which I just kind of want on a t-shirt now is "Clicks are not engagement." This is a little bit like how time on page is not necessarily a good metric for knowledge base articles also. I kind of want to have her back on the podcast just to talk about how clicks are not engagement. But yeah, so clicks are not engagement, period. And the tip I'm most interested in applying is Katie's requirement of having both learning objectives that you're kind of structuring the whole module around as well as a teaching scenario that also you're structuring the whole module around. So you take a fake company and a realistic but fake problem that needs to be solved. And your module should focus around how to solve that problem, using that narrative as tie down points, helping you bring in the feature set or the processes that you want to cover. So many advantages to this. Learners can identify with pieces of that scenario. They learn the nuance and complexity of your product. It probably isn't going to perfectly fit what they need, but it's going to give them a comparison, a really solid analogy to then extrapolate into what they're trying to do and how they want to use the product. It also keeps it more engaging, in addition to helping them draw those parallels. All really good things. Kate Mueller: [00:21:46] Also things that I'm not sure I had been thinking about very deeply. And that feels like the biggest genre difference between product documentation and product education, that explicit need to structure and format for learning and engagement, and providing those narrative structures to keep folks engaged and to help structure what you're providing them. I feel like a broken record saying this, but tech writing is so much bigger than product and software documentation. Since episode eight with Marcia Reifer Johnston and our conversation about whether cookbooks count as technical writing, my own definition of tech writing keeps expanding. I mean, at this point, I feel perilously close to climbing to the top of a tall building and screaming out, “It's all tech writing.” I mean, not everything is tech writing. There's definitely writing that doesn't fall in our purview, but instructional design and this type of educational content do feel like a niche form of technical writing to me. They use many of the same skills of someone writing software or product or hardware documentation, but with different formatting and outcome expectations, just like a different genre, but still a thing. My conversation with Katie really reminded me just how valuable tech writing skills are, and how many different places they can be applied, and whether you call that customer education, product education, or instructional design, it's an area you could seek to expand your skills into and potentially consider for a new role. Kate Mueller: [00:23:19] If your company already has an academy or an education function, reach out to the lead there and see if you can serve as a subject matter expert reviewing content, as Katie asks her tech writers to do. Or if they're looking for people to contribute, which most of us are in any form of tech writing, see if they'd welcome your contributions. See if you can design a little course or a module, and then add that work to your portfolio and also consider how you like it. This month, thanks to Katie's suggestion, I've requested Cammy Bean's book The Accidental Instructional Designer from my interlibrary loan program, and I'm really hoping to dig in there to deepen my understanding of instructional design so I can figure out, you know, where to take Owlcademy's first true learning module. Bonus points if I can use some of these upcoming webinars to test some ideas for content. I'm definitely hoping to have a little fun narrative structure in there, but we'll see how that goes. Anyway, I feel so thankful to get to talk to so many talented writers from all walks of life and so many different areas of expertise, and I'm so glad that you are here to join me on this journey. I hope you took something away from Katie's interview as well. Kate Mueller: [00:24:34] 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 just want 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. This could be you that I'm doing these reflective takeaways about, just saying. Kate Mueller: [00:25:12] 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.