Kate sounds off on content types
02/06/25 • 16 min
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:
- KnowledgeOwl Support KB
- Diátaxis content types for software documentation
- Dave Gash’s A Painless Introduction to Information Typing, which is a pretty solid introduction to Information Typing as it’s used in DITA and other frameworks
- The Good Docs Project
- Wisdom Wednesday on Use tags + Manage filters for fast docs updates/audits: Kate’s quick walkthrough on how she uses tags and Manage filters in KnowledgeOwl for content audits and updates
—
Contact The Not-Boring Tech Writer team:
We love hearing your ideas for episode topics, guests, or general feedback:
- Email: [email protected]
- Bluesky
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 replac...
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:
- KnowledgeOwl Support KB
- Diátaxis content types for software documentation
- Dave Gash’s A Painless Introduction to Information Typing, which is a pretty solid introduction to Information Typing as it’s used in DITA and other frameworks
- The Good Docs Project
- Wisdom Wednesday on Use tags + Manage filters for fast docs updates/audits: Kate’s quick walkthrough on how she uses tags and Manage filters in KnowledgeOwl for content audits and updates
—
Contact The Not-Boring Tech Writer team:
We love hearing your ideas for episode topics, guests, or general feedback:
- Email: [email protected]
- Bluesky
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 replac...
Previous Episode
Developer collaboration with Lorna Mitchell
In this episode, I’m talking with Lorna Mitchell, a technology leader, published author, tech blogger, and developer experience expert who is passionate about APIs and developer tools. We talk about why developers writing docs is good for both your devs and your docs, the best ways to build successful collaboration with developers, and more!
Lorna and I discuss her background as a developer who started doing documentation for her own resources and gradually moved into developer relations, developer advocacy, and developer experience. We chat about the wide range of writing she’s tackled–including books, readmes, and her blog–and why developers need to write to improve their skills.
We also discuss strategies tech writers can use to facilitate good collaboration with developers, including treating their role more as editors rather than writers; having a clearly-defined process with discrete, well-scoped requests for contributions; creating content type templates to streamline contributions; and having a second, shorter style guide for developers.
About Lorna Mitchell:
Lorna is based in Yorkshire, UK; she is a technology leader and developer experience expert who is passionate about APIs and developer tools. She is also a published author and regular blogger, sharing her insights on a variety of tech-related topics. Lorna serves on the OpenUK board, is on the Technical Steering Committee for OpenAPI specification, and maintains open source projects.
Resources discussed in this episode:
- Lorna’s developer style guide
- Diátaxis for content types
- Write the Docs’ Docs as Code resources
- Tanya Reilly’s Being Glue
—
Contact The Not-Boring Tech Writer team:
We love hearing your ideas for episode topics, guests, or general feedback:
Contact Kate Mueller:
Contact Lorna Mitchell:
Contact KnowledgeOwl:
—
Transcript:
Kate Mueller: [00:00:01] 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. Hi, I'm Kate Mueller. In today's episode, I talk with Lorna Mitchell. Lorna is a technology leader, published author, tech blogger, and developer experience expert who is passionate about APIs and developer tools. We talk about why developers writing docs is good for both your devs and your docs, and the best ways to build successful collaboration with developers. Welcome everyone! My guest today is a woman who I first discovered through a 'write the docs' talk, who made open API and API documentation actually makes sense and seem like a reasonable form of documentation. And as somebody with no background in API stuff, I figured, you know, if I need to interview somebody who qualifies as not boring, anyone who can make API docs feel not boring feels like someone I should have on the show. So I'm very delighted to welcome Lorna Mitchell to the show today. Hi, Lorna. Welcome.
Lorna Mitchell: [00:00:54] Hi Kate! That is a great intro, thank you so much for having me.
Kate Mueller: [00:00:57] You're welcome. I'm sure you never thought you'd be starting off thinking, wow, what a compliment to be called 'not boring'. But here we are, welcome to the pod. For our listeners, I came from the writing world and accidentally ended up in tech and have ended up writing a fair amount of software and product documentation and a variety of other things. But for me, that was always like an accident. I just sort of ended up here and it's worked. My sense is that you've had the opposite experience, where you started more on the tech side and have accidentally ended up writing some documentation sometimes. Is that true?
Lorna Mitchell: [00:01:35] I think that's a really good reflection. I've always liked words, but I have worked my entire career in software engineering of one kind or another. Along the way, it always seems to be, I've been in charge of multip...
Next Episode
Bridging the gap from “not technical enough” to “technical” with Janine Chan
In this episode, I’m talking with Janine Chan, a technical writer and Write the Docs community moderator. We talk about how feeling “not technical enough” is as much about attitude and approach as it is about knowledge and ways you can bridge the gap to a more technical future.
Janine and I discuss the fact that there’s no defined/established set of skills or training to become a technical writer. This lovely flexibility can also lead to a lot of imposter syndrome or feeling like you’re “not technical enough.” But through continuous lifelong learning, changing your attitude or the story you tell yourself, asking for help, and letting go of perfectionism, you can transition to a more empowered, technical version of yourself.
Along the way we discuss the wonders of indoor plumbing, the fact that growing up to a be a tech writer isn’t typically on kids’ radar, our tendency to get curious when we’re frustrated about something, the importance of trying to answer a question before you seek help, how to be generous in requesting help, how generally awesome and generous with knowledge people are, how the experience of knowing little makes us more empathetic writers, and so so much more.
About Janine Chan
Janine is a technical writer based in Calgary, Canada. When she's not writing software documentation or shoehorning sociolinguistics into conversations, she's usually either outside, or hunkered down trying to make room in her lap for both a knitting project and her cat. (She recognizes that "not-boring" is a relative term.) You can find her on LinkedIn and the Write the Docs Slack, where her inboxes are always open for more tech writing chats! She promises she won't write in third person like she is now.
Resources discussed in this episode:
—
Contact The Not-Boring Tech Writer team:
We love hearing your ideas for episode topics, guests, or general feedback:
- Email: [email protected]
- Bluesky
Contact Kate Mueller:
Contact Janine:
Contact KnowledgeOwl:
Join the discussion by replying on Bluesky
.
—
Transcript
Kate Mueller: [00:00:05] 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. Hi, I'm Kate Mueller. In today's episode, I talk with Janine Chan, a senior technical writer and a Write the Docs community moderator. We talk about that feeling of not being technical enough and ways to level up your technical skills so you can flip the narrative to, 'I'm a technical writer who just hasn't learned how to do this yet'. Hello my not-boring tech writers. I am so excited this week to be joined by a writer that I met kind of by happenstance. I gave a talk at one of the virtual Write the Docs Portlands a few years ago on Beating the Virginia Blues, and this woman happened to be my moderator for that session and ended up being amazing. She handled the other person who was doing Q and As audio networking with total aplomb. I can say she is both great under pressure and also not boring and a delightful human to boot. So I would like to welcome to the pod Janine Chan. Janine, welcome.
Janine Chan: [00:01:20] Hi, Kate. Thank you so much for such a kind intro. Oh man, all those AV issues. I guess I must have blocked them out.
Kate Mueller: [00:01:27] You've repressed them. It's fine.
Janine Chan: [00:01:29] Yeah, that's exactly what happens. And what a great talk it was. To be introduced to you by virtue of amazing athletic feats and also technical writing. Who could ask for more?
Kate Mueller: [00:01:42] There are two areas that have way more overlap than the average person probably thinks, because the number of people who messaged me after who were like, I've been a thru-hiker, or I'm thinking about being a thru-hiker, or I just really loved your talk. Apparently the Venn diagram of not-boring tech writers, and also people who enjoy doing outside things is pretty strong. There's a huge overlap there.
Janine Chan: [00:02:05] I love it. I love hiking, but I do lo...
If you like this episode you’ll love
Episode Comments
Generate a badge
Get a badge for your website that links back to this episode
<a href="https://goodpods.com/podcasts/the-not-boring-tech-writer-463340/kate-sounds-off-on-content-types-83747339"> <img src="https://storage.googleapis.com/goodpods-images-bucket/badges/generic-badge-1.svg" alt="listen to kate sounds off on content types on goodpods" style="width: 225px" /> </a>
Copy