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!
Resources discussed in this episode:
—
Contact The Not-Boring Tech Writer team:
We love hearing your ideas for episode topics, guests, or general feedback:
Contact Kate Mueller:
Contact KnowledgeOwl:
—
Transcript
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 ref...