Technical Writing is Part of the Conversation

Steve Arrants
2 min readJan 27, 2024

This updated article was previously published here.

Pexels stock photos

A number of years ago, we learned that the operations manual for California’s Oroville Dam hadn’t been updated in almost 50 years. While the manual itself wouldn’t have directly prevented the damage, it points to deeper, systemic problems with product documentation across industries. Too often, user documentation is dead last in priorities.

We spend so much time and effort creating and building amazing products and then neglect those needing help using them. It’s frustrating when you’re looking for a solution, and it is sometimes impossible to complete a task. Coming soon! the topic text makes me wonder what else isn’t finished.

With rapid development environments, creating and distributing software and services in rough betas is possible. And they’re often accompanied by online pages written by developers or marketers who know the product, but they’re too close. They document for power users, not for first-timers. But the first-time users are who you want to hook.

When we talk to the user, we must do more than ask what she wants. We must observe and ask why. And the why of these thought processes is important. Just as the UX work needs to be done for the product, use this data to help you create great documentation. This makes your product easier to support. It helps your product succeed in a crowded market. Having good, usable, accurate user documentation respects the end user. You don’t need printed and bound manuals. You can provide great documentation and support online. But you can’t do that without planning, effort, and writing to the user.

What it comes down to is working towards a successful relationship. You’re having a conversation with the user. Make the documentation a part of the conversation.