Search results

Should technical writers care about more than documentation?

Series: Testing your documentation

by Tom Johnson on Jul 14, 2015
categories: technical-writing

As a technical writer, your holistic understanding of the total customer journey allows you to extend beyond your doc-writing role to wear other hats with usability, quality assurance, product management, training, support, and more. But the more time you spend in these other roles, the less time you have to spend on documentation, which results in a weaker doc product.

In my previous post on communicating feedback from testing documentation, I noted how testing documentation leads to increased visibility and overlapping roles. When you start testing documentation, you discover bugs with the software, find ideas for product improvement, and have other opinions. You’re no longer just a quiet, introverted scribe but rather an active, vocal player with an increasingly team-centered role.

However, there are limits to going beyond the documentation role. It’s one thing to log and bug now and then, and to offer feedback to the product manager, but what if you start going full throttle in these directions, doing the following:

  • Logging 10 bugs a day based on your findings
  • Providing 5+ emails a day to the product manager suggesting improved UI, features, and other workflow
  • Combing through hundreds of support incidents to pinpoint customer pain points and needs
  • Analyzing all marketing messages for consistent terminology and messaging
  • Suggesting extensive usability principles to UI design (based on personas) to enhance the user experience
  • Analyzing button label text and other UI text for suitability with translation efforts
  • Interacting with customers to get feedback about features both present and planned
  • Inviting sample users into a special observation area where you can watch them not only use your doc but also use the system as well, essentially conducting usability tests
  • Creating eLearning tutorials to provide training to users, and even providing scoring and certificates of completion
  • Setting up identity access control workflows to provide authentication into a doc portal and other resources based on user roles
  • Drawing illustrative diagrams that show workflows, concepts, and other processes within the system and business context

The identity question

About 8 months ago, I was contacted anonymously by a regional STC conference planning committee (for Spectrum) to find out my reaction to the topic “More Than A Tech Writer…Beyond Tools, Beyond Docs.” This was the theme of their conference, and they were assessing the fit of their theme with a handful of prospective keynote speakers. They said:

We want this conference to focus on our identity, what we really do (which is often so much more than others think we do), how we are viewed, how we can change/shape how we are viewed. … We’d love to know your thoughts. Does this theme excite you as a speaker? What suggestions or brainstorms can you share with us to help us expand and/or refine our vision?

When I read the email, my thoughts immediately turned to the question of technical writer identities and titles. I’m familiar with that identity conundrum and have grown tired of hearing too many tech writers complain about being under valued, about being labeled “only a writer.” So I responded as follows:

If you want to focus on something more than help, more than publishing, more than most everything, then you might even be moving toward tech writers as content strategists. However, content strategy is not a topic that excites me. It’s actually a topic that I find frustrating because we all tend to do it to some degree already, yet so many people viciously defend the space as belonging to a unique elite.

I’ve actually explored the multiple-hat path before, when I presented a keynote to another regional STC conference about 5 years ago. I didn’t want to re-assess the identity topic.

But in reality, I never had a good conclusion for the many faceted roles that technical writers play. Maybe there’s more to think about? Should I move beyond doc into overlapping roles, or should I stick to my main responsibility and just focus on documentation?

The argument to stick with documentation only

When you start playing roles in quality assurance, product management, usability, eLearning, training, support, and user experience — in addition to documentation — you risk diluting the documentation product that you produce.

It’s simple math. You have only a limited time to spend on the documentation. Out of 100 hours, if you spend 30 of it doing roles outside the scope of your documentation stewardship, that’s 30 less hours that you have to spend on the documentation. Mathematically, the documentation might only be 70% as good as if you’d spent 100 hours on it. If you’re grading the effort, 70% is basically a C.

Ultimately these other roles are the stewardship of others. If QA does a crappy job testing the product and users later find bugs, stakeholders won’t point the finger at documentation. If the UI is confusing to figure out, the doc team doesn’t get the blame. If the support experience is poor, the doc team doesn’t have to deal with the complaints. If the engineers built features that no one wants, does the doc team get fired? No, product managers get the heat.

But if there are errors in the doc, or if the doc just sucks, then no one else is to blame but the doc team.

I recognize that this is a siloed, myopic attitude — and it’s not necessarily my own attitude. But there’s a strong logic to it.

Specialized roles help teams be more efficient. The factory model turns out more products because each person sticks efficiently to their specialized role. Even at a place like McDonald’s, everyone knows their place. Someone cooks the hamburgers, another takes orders, another cleans tables, another handles the drive-through, and another manages the employees overall.

If the hamburger cook suddenly starts taking orders at the counter, the hamburgers might burn. If the manager starts cleaning tables, he or she might overlook the employees who are taking too long on their smoke breaks. If the drive-through person starts cooking hamburgers, the cars begin piling up outside in long lines.

The argument for going beyond documentation

Now let’s flip over to the argument for going beyond documentation.

Unquestionably, the technical writer’s perspective is unique with the product. Not only do you have a holistic view of how the application works (similar to QA and product management), you also understand the business needs of the users, you’re familiar with sample user personas and contexts, you know the pain points that existing users have through support tickets, and more. Few other people have this holistic view of the application and user.

Give this holistic view, technical writers can bring a lot of value to a project. You can provide insights that no one else can because others don’t have your context and and knowledge. In fact, tech writers often have this same knowledge about multiple products, not just one (this moves tech writers beyond the understanding of QA and product management). If technical writers want to, they can start expanding their wings and start playing more of a content strategy role.

Or to put it another way, technical writers can start thinking about the whole customer experience from beginning the end:

  • How do customers first encounter the product
  • What are the messages promoted by marketing and sales
  • What is the experience of the UI
  • How do users process the documentation
  • What is the support experience like
  • How do users find and share answers in community contexts, and more

Technical writers functioning as content strategists can play a key role throughout the entire customer journey as they interact with the product at every customer touch point.

You could do all this, or you could simply focus on the documentation.

Why should tech writers care about anything beyond documentation?

One question is why technical writers should care about anything beyond their immediate responsibility? Let’s be real. Most tech writers work for a company documenting a product they don’t currently use, a product they probably never will use, and which they will never think twice about after they switch to another company.

Why should you go out of your way to play seven different roles not defined in your job description? When your salary, recognition, and assessment are evaluated against your core product, which is documentation, why should tech writers bother to move in so many different directions, moving from tech writing to these other roles — especially when no one expects (or event wants) you to do it?

Here are three arguments for moving beyond documentation:

  1. It’s more personally engaging. Writing documentation that few people read doesn’t bring a lot of enjoyment. It’s more fun to play content strategy roles since you exert more influence overall in the direction and quality of the product. You can have a bigger impact. It’s a lot more fun to be a power player on the team instead of a quiet mouse.

  2. When you have the larger vision of helping the user, your natural inclination is to move beyond just writing doc to playing these other roles. When you understand that your role isn’t to write doc, but to empower users, then you start thinking beyond doc. The company doesn’t need manuals. They need users who get past the “suck threshold” and start “kicking ass,” to use Kathy Sierra’s terms. Docs are just one tool for achieving this, and not always the best one.

  3. You owe it to the company because no one else has your perspective. Given that you have a unique perspective that provides you with a holistic understanding of the user from beginning to end, you owe it to the company to provide as much value as possible based on your vantage point. Sure you’ll step on shoes and piss people off, but the product will be much better for it. No one else has this same point of view. They’re all working by looking at the product with a microscope in their own little domain.


You’ve probably gotten a sense of my mixed emotions about playing so many external roles beyond documentation. Sometimes I’m gungho about it, and other times I think I barely have time to focus on documentation.

Documentation can always be better than it is. It can have more visuals, more tutorials, more accuracy, more linked glossary terms, better navigation and findability, more responsive styling, and so on. When I find myself playing another role, I know that the documentation suffers. At the same time, the product overall improves, which helps the user experience as well.

What do you think? Where do you draw the line with your role? Should tech writers look for opportunities to go beyond documentation, or is the factory model where everyone has a specialized, highly focused role a better model to follow?

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.