The Not-Boring Tech Writer – Details, episodes & analysis

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: tnbtw@knowledgeowl.com
• Bluesky
• LinkedIn
  
  

Contact Kate Mueller: 

• LinkedIn
• knowledgewithsass.com
  
  

Contact KnowledgeOwl:

• KnowledgeOwl.com

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:

• tnbtw@knowledgeowl.com
• Bluesky
• LinkedIn
  
  

Contact Kate Mueller: 

• knowledgewithsass.com
• LinkedIn
  
  

Contact Lorna Mitchell: 

• Lorna's website
• Linkedin
  
  

Contact KnowledgeOwl:

• KnowledgeOwl.com

Folk working in technical communication—whether they’re academics or practitioners—through their own unique skill sets, perspectives, and experiences, often discover best practices to excel at their job. These hard-earned insights would likely benefit others facing similar challenges; however, silos often keep folk in technical communication from quickly disseminating what they’ve learned. 

That’s why Dr. Chris Lam—technical communication professor at the University of North Texas—created CrowdsourceTPC: a crowdsource platform that gives folk in technical communication and opportunity to share their insights and little wins—giving others an opportunity to use and adapt them for their own needs. 

In this episode, Chris joins us on the podcast to discuss the inspiration behind CrowdsourceTPC and how others can make the most of the platform.

Show notes: 

• Chris Lam on LinkedIn
• CrowdsourceTPC

For the civically-mind technical writer, there’s a growing movement in cities across the world where technical writers can use their skills to better their community. It’s called Open Data Day: an annual celebration of open data groups around the world partnering with local governments to use open data to achieve a shared goal in the community. 

From analyzing environment data to tracking public money flows, open data day gives citizens—from data folk to advocates—an opportunity to get the data they need to take action in their communities.

As a tech writer, you may not initially see how your skills fit into open data. However, as you’ll learn in this episode, success open data day’s need compelling narratives to complement outcomes, tutorials to teach people how to access the data for their own uses, and much more—all areas in which the tech writer succeeds. 

That’s why, in this episode, I have Jesse Hamner and two-time guest on the podcast—longtime open data advocates who’ve seen first-hand the value of the tech writer. 

In this episode, Jesse and Kyle help us understand the value of open data and how the civically-minded technical writer can get plugged into this exciting movement.

Show notes: 

• Open Data Day
• Skill #14: Contributing to Open Source Projects
• Jesse Hamner on Twitter
• Kyle Taylor on Twitter

As products and services reach markets outside of their geographic origins, organizations must consider how to translate and localize their existing documentation. It’s a must, as these new users will need to refer to a knowledge base. 

But how exactly do organizations translate their documentation? Do they copy and paste all of their content into Google Translate? Do they hire technical writers who speak and write the language of the new market? 

As you’ll learn in this episode, successful organizations partner with translation and localization vendors, who ensure users in new markets understand the content. 

To help us dig deep into this skill, we have Mike McDermott on the podcast: Director of Language Translations at MadTranslations, a translation service created by MadCap software. For nearly eight years, Mike has helped clients translate their content into several different languages.  

In this episode, Mike share insights he’s learned along the way to ensure any organization has a seamless, successful translation process, including how to research the right translation service, who to get involved in the research process, and how to create content optimized for translation.

Show notes: 

• Skill #28: Researching as a Tech Writer
• MadCap Software
• MadTranslations
• Mike McDermott on LinkedIn

No matter your industry—tech, nonprofit, marketing—your organization likely needs a knowledge base software, a dedicated place to capture essential knowledge.

However, choosing the right knowledge base software can be challenging—and takes much more work then a quick Google search. You need to understand the core knowledge problems within your organization; compare softwares that, on the surface, may look a lot alike; and get buy in from key players who’d actually use the knowledge base.

That’s why in this episode, we have Kate Mueller on the podcast: Support Sorceress and—I kid you not—cheese monger at KnowledgeOwl: a knowledge base software that, as they share on their site, makes one thing - awesome knowledge base software. 

Kate has worked with several different knowledge bases throughout her career and, at KnowledgeOwl, works with current and prospective customers across the world to help them discover how knowledge base softwares can help address their needs.  

In this episode, Kate reflects on her career—both as a user of and support member for knowledge base software—to share the criterion you should consider as you choose the right knowledge base for your organization, including how to get started in your research, how to get  company buy-in, and which essential features you should look for in a knowledge base. 

And, in the end, Kate shares a few of her favorite knowledge bases—KnowledgeOwl and beyond—to jump-start your research.

Show notes: 

• Bloomfire
• Guru
• ReadMe
• Kate’s blog on The Trek
• Kate on LinkedIn
• Kate on Instagram
• KnowledgeOwl blog
• KnowledgeOwl support documentation

As prospective tech writers look for ways to get into the tech writing field, many pursue internships. And understandably so: internships give prospective tech writers hands-on experience in tech writing, giving them an opportunity to boost their skills and get a feel for the industry. 

However, finding that tech writing internship can be challenging, especially if you aren’t pursuing a tech writing related degree in university. That’s why, in this episode, we have German tech writer Joachim on the podcast, who’s six weeks into his first tech writing internship. 

Joachim has learned several lessons about how to find and thrive in a tech writing internship, which you’ll find helpful no matter where you live.

One of the most important skills tech writers can have is the ability to analyze their audience—researching who’s using the product their documentation, understanding how they it, and most important, ensuring their goals are reflected in the documentation. 

But as tech writers research their audience, digging deep into insights such as demographic and preferred device, tech writers can, admittedly, get caught up in the technical side of audience analysis and dismiss opportunities to understand their reader as a whole. 

That’s why in this episode, we have Alexander Yant on the podcast: occupational therapist turned tech writer advocate who, as he’s searched for tech writing opportunities for himself, has reflected on his career in healthcare to share must-have insights for tech writers hoping to better understand their audience. 

In this episode, Alexander shares how you can understand your readers as a whole, including why empathy is one of the most important aspects of audience analysis, how tech writers can boost their audience analysis skills, and how effective audience analysis can demonstrate your value as a tech writer.

Show Notes: 

• Chris Lam on The Not-Boring Tech Writer
• Bri Hillmer on The Not-Boring Tech Writer
• Alexander Yant on LinkedIn

All of the help resources tech writers create, such software documentation, video tutorials, or blog posts, require research. Imagine creating a document to explain a new feature before, say, even understanding how customers actually use the feature. 

Tech writers use several different resources to research the information they need, including conversations with developers and support and reviewing support tickets. But, if you’re like many writers, we’ll often seek too much information and face information overload, uncertain what to document. 

Or, as we’ll learn from this episode’s guest, we miss an opportunity to research the domain in which we work—a must for any tech writer, no matter their industry.

That’s why, in this episode, we have Margaret Eker on the podcast: tech writer at Magento, an Adobe company, and somewhat longtime friend since our days hiking in the forests of Portland Oregon for Write the Docs 2016. 

Margaret prides herself as a researcher. And, countless times, has witnessed her work and relationships with her colleagues flourish when she dedicates herself to understanding the domain in which her company exists. 

In this episode, Margaret shares how you can boost your research skills as a technical writer, including how tech writers traditionally research new features, why tech writers should research the domain in which they work, and which steps you can take today to boost your research skills.

Show Notes: 

• Margaret on LinkedIn
• Margaret on Twitter
• Bri Hillmer on creating just-in-time documentation

As tech writers consider how to stay relevant in the field, many look to GitHub—the git repository service where people host their open-source projects, allowing others to contribute as well. And understandably so: as the demand for tech writers specialized in developer documentation grows, GitHub gives tech writers low-lift opportunities to ramp up their skills. 

That’s why, in this episode, we have Tad Dieken on the podcast: two-time guest on the not-boring tech writer podcast and tech writer at Accuray, who recently completed a week straight of GitHub contributions, ranging from creating onboarding guides for new tech writers to translation. 

In this episode, Tad shares how to get started contributing to GitHub, including how to find projects that interest you, how to overcome imposter syndrome in GitHub, and which new skills you may learn in the process.

Show Notes: 

• Write the Docs
• Write the Docs Slack
• Learning GitHub course on LinkedIn
• Skill #14: Contributing to Open-Source Projects
• Tad on GitHub
• Tad on LinkedIn