9 posts tagged with "Friends"

So often the SMEs we work with want to throw people into the middle of the conversation.

I was talking about Ngombor Community Development Alliance in the Write the Docs Slack recently and someone asked me what Ngombor had to do with documentation.

It was an excellent question as I'd thrown some Ngombor information at a channel without contextualizing. I'd been a terrible technical writer, marketer and organizational storyteller. What did fundraising for a community organization in Uganda have to do with technical writing? For some, it was a logical continuation of a conversation. For others it was baffling to be suddenly thrust into the middle of a conversation where they did not have the context to understand what I was talking about. In the heat of the moment, how would someone tell the difference between me and any random person trying to sell a product?

So often the SMEs we work with want to throw people into the middle of the conversation. They've been working on something for months, maybe years and they just want to display the logical conclusion. It's frustrating. I don't know how many times I've needed to help engineers understand that a little bit of context, a little bit of grounding information at the top of the doc is not patronizing, it's not unnecessarily slowing people down. Context and introductory information helps people (or machines), who are not in the middle of whatever the conversation is, access the meaning of a document. It helps people who might not have the precise words for describing their situation, find their way.

And I must laugh and pause here, and I hope you are laughing too. Most of the world doesn't really play baseball, it's not global terminology! When it comes to jargon, inside baseball is a little inside baseball!

Infodumping is when you provide a whole lot of information all at once. It's a term that's been used for some decades when critiquing literature and has been adopted by autistic communities to refer to our tendencies to excitedly enthuse on a topic.

Documentarians (aka technical writers, content champions and word nerds) are prone to this trait. In some ways technical writing is an ongoing wrestling match with infodumping as we take on vast amounts of information, process and subject matter expertise and transform it into content that can be used and understood with greater ease.

In an increasingly remote world, our non-technical writing colleagues can find our facility for writing things down a little bit overwhelming. It can be especially frustrating for technical writing when even asking questions can trigger overwhelm in others as it floods their brain with new angles and questions. We can feel stuck in a bind where we're simultaneously told to ask questions, but also please don't communicate so much!

This is why when I was putting together the Neurodivergent Quality of Life Prioritization Matrix management of over enthusiastic infodump over chat was one of the first criteria I listed.

In this blog post I share some tips and tricks I find helpful, as well as some advice from fellow Write the Docs peers. We'll never get it perfect, but perfect is never the point.

If you want to jump straight into the Agenda and Minutes Template:

• Create your own copy
• Master document, where you can leave comments and provide feedback

Minutes are important, and not just how we choose to use the finite amount of time we have in life. Minutes are recordings of decisions and discussions that occurred during a meeting. Done right, they are powerful and meaningful. As a technical writer, I've often used an agenda and minutes to drive decision making, make next steps clear and to manage my own enthusiastic use of workplace chat!

I have two strong opinions (aka hot takes? but is it really hot?). One is that technical writers have a vested interested in good meeting minutes and should just start writing them if the minutes are falling short.

I had a great conversation with Kate Mueller on the Not Boring Technical Writer podcast. The actual interview was a lot longer as we got quite carried away, so kudos to the editors for squeezing it down to size.

Connecting permaculture and documentation with Liz Argall

We cover a lot of ground in the episode, including how to help engineers overcome shame that can limit documentation, the glory of the right metrics used the right way and what can happen if you throw yourself into processes passionately. You'll see connections between what we spoke about and my recent Attend to the Work blog post.

One of the bits that didn't make it into the episode was

This essay started as a love letter to mindfully turning up. I wanted to write about the power that comes from turning up a little bit at a time consistently. As I attended to the work of blogging regularly it evolved to be a love letter to processes, structures, systems and their interconnections. This essay gives you a tour of philosophies and metaphors that may feel disconnected at first, but all feed into creating meaningful, effective work while avoiding burnout.

Due to the nature of this essay, I've only done minimal edits while typing. This essay is a love letter after all, and it wouldn't do to over work it!

Let's begin​

Over the last few blog posts, I've shared some resources for mindfully turning up for your docs and for yourself.

If you look at these resources you might get a sense of overwhelm. OMG, there's so much to do and I haven't done it all! It's easy for your mind to shut down and decide, if you can't do it all, what's the point?

If you want to jump straight into Search Term Analysis spreadsheet:

• Create your own copy
• Master document, where you can leave comments and provide feedback

About​

When we talk about content quality, findability is an important factor that extends beyond clean architecture. "Can the user find the data?" is a common question. Can the user find the data if they start with a Google search takes us deeper into this investigation.

At the Write the Docs Conference in Portland this year I gave a lightning talk on "Google Magic!" It showed how and get insight into your documentation in five minutes. Through this approach you can get a clearer understanding of your users and identify the most impactful ways to improve your docs.

This article goes into a bit more detail and provides a template for conducting several kinds of search term analysis.

Jump straight straight into the Neurodivergent Quality of Life Prioritization (NQLP) Matrix:

• Create your own copy of the NQLP
• Master document, where you can leave comments and provide feedback

Creating a framework to manage the brain weasels​

Whenever life doesn't go to plan, there is an opportunity to self reflect and find opportunities to learn and grow. This is a useful habit to cultivate and can turn adversity into an alchemical experience.

What is not helpful, is to look at the data, look at all the variables that go into being a human and come to the conclusion that you are a trash human/need to improve across all the criteria. This is especially challenging when you're not even sure what the criteria are, or perhaps the criteria changes as you analyze yourself from different angles.

Searching for work in 2025​

This blog post covers two topics:

• The state of things
  • What it's like to be a technical writer right now and how we can carve out better spaces for ourselves.
• Prioritization matrix
  • Skip straight down to this to get going with a tool that can make it easier to pursue your job search or career change dreams.

Welcome to my new technical writing blog.

First, a big shout out to the following thought leaders who have encouraged more technical writers to share their knowledge and opinions.

• Fabrizio Ferri Benedetti
  • Terrific human whose blog posts stir conversations and help us build a better vocabulary for what we do.
  • Technical writing has a depth issue is a powerful call to action for more of us to step out of the shadows and own our expertise.
• Not-Boring Tech Writer Podcast
  • In particular, The craft of technical writing with Marcia Riefer Johnston talks about the snowballing power of sharing a small tidbit of information and then building on it.
• Write the Docs Slack
  • Write the Docs is a global community of people who care about documentation.
  • The Slack channel contains a lot of expertise. It's been great to hear all the different voices and it is why I went to my first Write the Docs conference.
• Write the Docs, Portland (USA)
  • A wonderful annual conference for documentarians (be they technical writers, programmers, managers, project managers, user support agents or wild enthusiasts).
  • At the conference this year (2025) I shared multiple frameworks with folks and gave a Lightning Talk. These topics will form the basis of my initial blog posts.

Over the coming weeks I'll share various tools and tricks for analysing your docs and getting insights into your users and products. I'll also share some resources for a more holistic approach to the work we do. When we think about content quality, we often focus on the docs themselves, when workplace environments and physical humans need just as much attention.

If you have thoughts, feedback or ideas you'd like me to expand on, you can email me at liz@lizargall.com or create an issue in the GitHub repository of this website. If issues ever need to be moderated I'll use the Write the Docs Code of Conduct as the framework, AKA don't be a jerk.

If you use any of my ideas and would like to share how they're going for you, I'd love to hear from you as well.

Thanks to my fellow documentarians, you make it a pleasure to write for.

If you'd like to get an email every time there's a blog post, subscribe to my technical writing mailing list.

Good things,

Liz

liz@lizargall.com

11 May 2025