Technical writers sometimes face a frustrating dilemma where stakeholders view their work as either “not enough” or “too much”. This post explores how to show the unseen labor behind docs, build team trust, and navigate the effort heuristic in tech.

The elusiveness of it all

You’re about to read my blog post. What if I told you it took me 30 minutes to write? 3 hours? 3 days? The effort heuristic tells us that our perception of the quality of someone’s work changes based on the perceived amount of effort it took to produce it. This post took me 4 weeks of procrastination, by the way.

As long as I’ve been working in tech, I’ve been thinking about how I can make sure my colleagues understand what I do and the value of what I bring to the table. I started with technical writing, and now I’m focused on product management. But across functions, the main question remains: how can you communicate the amount of time and creative space you need, and how do you build trust within a team?

As I was gathering my thoughts on this topic, I could feel how elusive it was. Where exactly does this problem lie? I felt the core of the idea I wanted to describe, but it was difficult to put into words. I think I’ve finally put my finger on it, and the elusiveness came from it being a contradiction:

  • Sometimes it’s perceived as not enough
  • Sometimes it’s perceived as too much

The dilemma, as I see it, is that stakeholders can sometimes over-prescribe solutions (solving for “not enough, there should’ve been more”) or approach collaboration by viewing writing processes as a bottleneck (solving for “too much, there should’ve been less”).

It’s not enough

You were assigned a ticket. You’ve worked on it and submitted it for review. And then you get this comment:

👨‍💻: "Maybe more screenshots? Also, this guide only has 3 sections, it's very short."

Note: The 👨‍💻 quotes here and below are fictional, for illustrative purposes.

We’re experts in what we do. We’ve gone over countless style guides and created our own. We spent years honing the craft. We defined word lists for the products we work on, maybe even spent a substantial amount of time in our careers carving out our space in a specific industry.

I’m currently reading Think Twice and stumbled upon this pretty straightforward quote:

The experts internalize the salient features of the system they are dealing with, freeing attention for higher-level, analytical thinking. This explains a number of the universal characteristics of experts, including the following:

  • Experts perceive patterns in their areas of expertise.
  • Experts solve problems much faster than novices do.
  • Experts represent problems at a deeper level than novices do.
  • Experts can solve problems qualitatively.
— Michael J. Mauboussin, Think Twice: Harnessing the Power of Counterintuition

Put bluntly: as technical writing experts, sometimes we do know better. Sometimes you really need just one day of work to finish something. It doesn’t make the work any less valuable.

I believe there should still be curiosity in getting to the root of the problem the other person is pointing to, but it should never be a case of just doing something because someone said so. Something I learned when I started working in product management is: “Don’t tell me the solution to use. Tell me the problem, and I’ll figure out how to solve it.”

Dig past the solution offered. Figure out the concern behind it. It helps you incorporate unique ideas and challenge your assumptions without necessarily surrendering your expertise.

It’s too much

And then we can still find ourselves in a ticket with a stakeholder typing these words in a comment: “The release is tomorrow.” They created the ticket a day prior.

👨‍💻: "Why does the documentation for this feature take so long?"

It means there’s a system in place where stakeholders have come to expect this from us. Where an unspoken agreement was established that this amount of notice is acceptable and this is how much time it takes. We never showed how much effort it takes to produce the work. Short notice can be acceptable for some situations. Work can be unpredictable, and it’s important to be flexible in certain cases. The danger is when it starts creeping into the day-to-day. After all, nothing is more permanent than the temporary.

👨‍💻: "Here's text I generated from code, can't you polish it a little and use it?"

Not all tasks are equal. A technical writer can quickly turn around a task they’ve done a dozen times before. But as new functionalities get added to the product, new ways for customers to interact with it appear, the technical writer would need to:

  • Use and get used to the new product
  • Test it, and test it again
  • Understand customer use cases
  • Figure out where to put it within the architecture of the docs
  • and so on…

It’s an iceberg. The visible part: the page with the docs. The invisible part includes, to name a few: editing reusable snippets, replacing updated terms throughout the docs, setting up redirects, testing different layouts to see what works best, solving merge conflicts. In some cases, it makes sense to communicate the invisible part, via an internal page describing the writing process, for example.

👨‍💻: "Why are you spending time interviewing three different engineers?"

Technical writers are usually the voice of the customer. To write something useful and usable, we need to adopt a customer persona. Customer LARPing, if I may. When we talk to stakeholders and ask questions, we’re doing that on the customer’s behalf. This is an integral part of the process that can’t be shortcut. Docs are not a bottleneck. Docs are a stress test and a sanity check.

The exploration continues

This is my first attempt at addressing it, but I foresee myself coming back to this topic in the future. I’ll be covering it again at a TechKomm workshop in Copenhagen this September. Come by to say hi and to offer your ideas on how we could solve this together.

Comment