The Not-Boring Tech Writer

My current in-flight projects include updating nearly all of our documentation to reflect major changes to our user interface, which includes changes to screenshots, navigation options, and section/subsection labels. I’m also working on my long slog to convert all our screenshots from .png to .webp format. As I make all of those updates, I’m bringing our content into line with our current style guide (the first time I’ve used an explicit style guide in the KnowledgeOwl Support Knowledge Base).

I recently finished teaching my first Knowledge Management Master Class with KnowledgeOwl. This was mostly a success, though it was a sharp learning curve for me and I’m already full of ideas on what to do differently next time. It also humbled me since it made me view my own docs through the lens of all the best practices I was suggesting people employ–and realizing how often my docs fell short.

For me, the most fascinating takeaway was really digging into the concept of concept types or information typing. I’ve never done this as an explicit, intentional exercise. After researching various approaches, I’m sold on the underlying concept. My plan is to create some templates for each major content type, using The Good Docs Project’s templates as a starting point). I’m then going to use those templates as I update content in our Features category to test and refine the templates before gradually applying them to the entire knowledge base. I’ll be using tags to track my progress and identify the content type for each page, too. In Episode 5, I’ll report back on how I’m doing in my endeavors!

—

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

—

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 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, or both. I'm recording this episode in early December, right after Assad's ouster and the murder of the UnitedHealthCare CEO, just for some context. So first up, what am I working on? I'm in the midst of making a lot of updates to the KnowledgeOwl support knowledge base. KnowledgeOwl has released a lot of UI changes in the last couple of months, which of course I got behind on, so now I'm working to get our screenshots and text updated from those changes, while knowing that there are more changes coming in the next few months too. This has been a lot of changes. We changed our whole color palette, we changed a lot of the user interface key elements, we also just rolled out a totally different left hand navigation so I've got my work cut out for me. But it's a good exercise because it's prompted me to really evaluate how useful a lot of those screenshots are and whether we actually need them. In particular, there are a lot of older articles where I used screenshots of code as a final example for some of our step by step documentation, and I'm gradually replacing those screenshots with formatted code blocks just to reduce the screenshot maintenance burden.

Kate Mueller: [00:01:41] I've also been updating screenshots. We're moving away from PNG format and into WebP format, just to try to keep our file sizes a bit smaller and maybe give our SEO a tiny bit of boost. That change came out of me writing our 'image best practice guide' for customers and actually researching image best practices. So that's been a fun change. And last but not least, after years of having a fairly vague style guide, or no style guide, I've written a clear one. So as I make all of these updates, I'm bringing the text into alignment with the new style guide. All of that has already been in flight for a few months. I also recently finished leading a Knowledge Management masterclass with KnowledgeOwl. And as the old saying goes, the best way to learn something is to teach it to others. So I'm thinking a lot about things like content types, information architecture, information scent and findability and good metrics for success. Teaching the class was really humbling to say the least. It's kind of impossible for me to teach a class on this stuff without feeling mildly embarrassed at all the ways my own docs don't follow the best practices I'm talking about. And to be honest, this was the first time I've really had the time and space to sit down and critically view my documentation through some of these lenses, these big pictures.

Kate Mueller: [00:03:12] I'm usually so busy trying to keep things up to date that I don't really take that step back to look at the big picture. And now that I have, I'm overflowing with ideas on how to improve my docs. So many ideas, and I've had to really sit down and evaluate and try to pick just one to focus on. So top of mind for me today is one of those ideas, content types. The masterclass really made me research and discuss content types, and I find that I keep thinking about them and thinking about how I haven't been intentionally or consistently using them to structure our content. I mean, clearly our docs have survived this long without me doing that, but I've been thinking about ways to make it easier for more members of our team to contribute to the support KB. The style guide standardization has been a big piece of that, but I believe content types with templates are the next step. They would make it much easier to onboard another writer, or to ask other owls to update docs in my absence.

Kate Mueller: [00:04:15] For those of you familiar with content types, I'm thinking mostly about the common information types used in frameworks like Dita. The content, task and reference. Or the four types that Diataxis uses, explanation, how to guide, reference and tutorial. And for those of you who've never heard of content types, I'll put some links to those resources in the show notes. But the basic idea behind content types or information types is that each type serves a different purpose for your audience, and should be structured to address that purpose. Defining and using types means that you can consistently structure the same types of content in the same ways, which reduces cognitive overhead for your readers and also provides clarity for your content creators. It just simplifies a lot of the process, it ensures that you're being consistent across the board. All of those things should lead to higher quality level documentation. What I'm thinking most about is not necessarily the specific content types themselves and what they should or shouldn't look like or the differences between them, but the act of typing in general. Of putting the focus on having each topic as a specific type, and therefore each topic having a specific structure, purpose and layout, and having that be consistent across my entire knowledge base. Now, that's a practice I've loosely been doing for a long time, but I think I've done it in a subconscious way. Honestly, a subconscious, inconsistent and constantly evolving way. I have some docs that are very well structured around an implied type, and others that are a bit of a smorgasbord of different types.

Kate Mueller: [00:06:05] I inherited the support KB in 2018, and I did a major content reorganization in late 2019. And if I think about the history of these docs, they've evolved over time based on my own changing ideas around organization style, and I guess what I'd call an intuitive feel for how the docs should be, which includes content types. But those weren't things I ever wrote down, they weren't things I tried to explain to others. I've never really taken the time to sit down and say, this is exactly what should be in this particular type of content. For example, how-to docs that I wrote back in 2018, I'm kind of embarrassed by now. They're really different from the way that I write how-to docs in 2024. And there are some old docs that I inherited in 2018 that I've kind of avoided overhauling for structure or layout or things, because I couldn't really quite put my finger on what was off about them. I knew they didn't feel right, I just couldn't figure out what was wrong and therefore what the best way to fix it was. So I've just kind of ignored them, I've done surface level updates. I'm thinking that reviewing my docs through the idea of content types is going to help me actually put my finger on what's off with those older docs. Nearly every single one of those docs is unclear about what content type it is, so it's trying to be several of them at once, kind of mixing and smashing together different types. So there will be a little bit of explanation and then some how-to or task based steps that might have some explanation thrown in, maybe a little bit of reference for good measure. There's just a lot going on in these docs. No amount of style changes will fix what's going on there, it just all feels a little bit haphazard. But defining some clear types and some templates for each type, and using that as a structure to review all my docs through as a framework, that feels like a fantastic move forward for me.

Kate Mueller: [00:08:22] I'm also a bit lucky, I guess if you can call it that, that I'm already in the midst of making all these updates from the UI changes because it's giving me an excuse to revisit a lot of my docs anyway. And maybe my other little bit of luck here, as I mentioned I'm recording this in early December, and typically December and January are our quietest months at KnowledgeOwl generally in the support world and in the many hats that I wear, they're very quiet months. We typically don't release large things this time of year, we have a lot of folks who are out, a lot of our customers are out so there's a lot less coming into our team. It's been the time of year that I've tended to tackle really large projects. In 2019, when I did that big reorganization, I did that in December. I've used this time for big content reviews or audits in the past, I've rewritten entire sections of my docs, or rolled out major theme changes or reorganized corners of the content. I just find that it's a lot easier to do that around the holidays because stuff's so quiet here. So I'm thinking of this as, I can dig into it in December and January, and that's a gift that will just keep on giving for me for the rest of 2025.

Kate Mueller: [00:09:45] This episode is sponsored by KnowledgeOwl. If you're looking for an 'owl-in-one' solution to keep your software team's docs organized, KnowledgeOwl has you covered. KnowledgeOwl offers content access control for internal and public docs, flexible customization, robust security, and friendly support. Learn more and sign up for a free 30 day trial at knowledgeowl.com.

Kate Mueller: [00:10:12] So my plan, I'm going to start with the three information typing types, mashed up with how they overlap with Diataxis. So for me that'll be explanation how-to and reference content types. I'm going to build some templates within the support KB for each type. I'm probably going to use the good docs content type templates as a starting place for those, and then put my own spin on them that feels appropriate for our content. And then I'm going to pick one top level category in the support KB to test those templates with. As I've thought about this, I think I'm going to do it with our features category. That category is, I think it's our third or fourth category listed in the content hierarchy, and it contains a subcategory for each discrete feature that isn't about writing content, but the features around writing content, getting feedback, sharing it, that kind of thing. This category for me is a really good testing ground for those templates, because each feature is its own subcategory, so they're split into these nice bite sized chunks of content, mostly. And also, it's an area that I've always been a little embarrassed about because there is inconsistency from feature to feature and how those subcategories are laid out. Some of those features haven't been updated in a while, like our contact form docs, which are some of the older docs I've struggled to figure out how to update, so I'm going to jump in wholeheartedly on these. There's some talk around Diataxis about using content types to dictate your information architecture, I'm not going that full in on it. I think the content types will somewhat inform the information architecture, but I'm not going to be really rigid. I don't think that most of my readers necessarily think in content type, so I'm trying to figure out an information architecture that logically groups content types together without having it be all about what the type is for our readers. What I imagine I'm going to do is try to create a standard layout across each of those feature subcategories from a content hierarchy perspective, and then overhaul the content within them to match the content type templates that I've come up with.

Kate Mueller: [00:12:50] The other thing that makes the features category a good guinea pig, is that it's just a little bit smaller than some of the other top level categories like 'Write the Docs' or 'Look and Feel', which have boatloads of content in them. I'm thinking this will be both large enough for me to see a substantive difference, but small enough that I could actually get it done and be able to share it with the team and get some feedback that way. Once I get through the features category, I'll have to make some decisions about where to go next, and I'm sure that it's all going to take me longer, since I'm also updating for the UI changes and the style guide and the screenshot formats that I was already working on. It's going to be a labor of love for sure. Along the way I'll also be using some of my personal tried and true metadata driven strategies to manage and make these changes. In the KnowledgeOwl world, I use internal tags for that. I'll go through and bulk tag all of our articles to say that it needs content type review. Then as I review individual articles, I'll add a tag indicating what content type it's using and then remove the tag indicating that it needs review. I'll use a manage filter so I can see my numbers decrease as I review stuff, just to give me a nice little dopamine hit that, yes, I'm making progress. Because of that, I should be able to share some stats back to you about how this project goes in my next solo episode. I promise I will share that even if the numbers are embarrassingly low because of the holidays and other things. But I think it's important for us to recognize and maybe normalize that a lot of the work we do is behind the scenes, but also, it's not always fast. It's not always easy. A lot of the labor gets hidden, but then my hope is that I put this work in and then the reader experience becomes that much more improved. We'll see how that goes. By the time you hear this, we'll be past the holidays and into 2025 so I'm going to close this episode by saying, I hope 2025 gets off to a good start for you, and that whatever insane docs project you decided, that holiday you decided that you wanted to tackle in 2025, I hope it goes well.

Kate Mueller: [00:15:25] 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. Our theme song is by Brightside Studio. Our artwork is by Bill Netherlands. If you have feedback or ideas for a topic or guest idea, shoot us an email at tnbtw@knowledgeowl.com or message KnowledgeOwl on LinkedIn. If you want to work with me on knowledge management coaching, go to knowledgewithsass.com. Until next time, I'm Kate Mueller, and you are the not-boring tech writer.