First: Hello to everyone who found me through Tom Johnson’s link! Thanks for taking a look at my blog, and I’ll do my best to keep it interesting.
Phil’s comment on my last post made me think about something that’s bothered me for years: Why isn’t the docs team allowed near customers?
Phil is a great tech writer, and an even better friend. I’ve long envied his mastery of doc creation scripting. And like almost every other tech writer I’ve worked with (including me), he rarely gets to talk to the customers he’s creating all those docs for.
Why are we kept in the back room?
The first idea that hit me: Is it because the documentation team is part of engineering? And no one lets the engineers get near the customers, right?
Do other departments (sales, marketing) assume that everyone in engineering is an antisocial train wreck who will send your customers screaming to your competitors?
Maybe it’s because tech writers, like engineers, tend to be too honest. Engineers/programmers build the product, and we document how it works (instead of how it’s supposed to work, or how marketing or sales might want it to work). Maybe the concern isn’t that the engineers/tech writers will have access to the customers, but that the customers will have access to the people with inside knowledge and a distressing amount of honesty.
I kinda like that theory.
That can’t be the only reason
As a young tech writer, I asked my managers about this. The answer was usually “Sales doesn’t want us involved in those discussions” or “I don’t know.” A lot of tech writers have accepted this; so did I, for a long while.
Let’s be honest: It’s easier to not talk to your customers. It’s easier to make assumptions about how they’ll use your products. We can talk to sales and support and PMs, we can build personas, and we can tell ourselves that we’ve done enough research.
And I do mean “we”: I’ve settled for this method for a long time.
Why I’ve settled for an imperfect process
And “imperfect” is being kind. But I’ve done it because I’ve been busy. Often too busy to take on another set of tasks, tasks that would start with political maneuvering with other teams and executives to gain access to customers. That’s just the first step, and it’s exhausting.
Meanwhile, docs aren’t getting written. And my managers often deflected me with that: “We’ve got a release coming up; we don’t have time to interview our users! Anyway, they haven’t used this version, so they won’t know what to ask.”
I’ve used that excuse, too. And although it’s true, it ignores something: Your customers know what they want. Do they want entry-level instructions? Do they ignore those and go straight to the reference docs? Do they want best practices, examples, code samples, use cases?
Maybe they want infographics and videos. Or maybe they learn best through interpretive dance. You don’t know, do you? I certainly didn’t.
Why we should talk to our audience
I said that your customers know what they want: I’ve had people (usually project managers) tell me that customers don’t really know what they want, and if we just do what they want, they’ll never get the full value from our product.
Now that I’m moving towards a customer success role, I can understand and even appreciate that point of view.
But as technical writers, we’re always saying that we’re customer advocates. We serve our users, and our role is to point out when the product is difficult to use, when the installation process is hopelessly complex, and when the APIs don’t make sense.
We have to assume that our users know what problems they want to solve (why they’re using the software), and what questions they need answered (why they turn to the documentation). As tech writers, we need to know both of those things, since that informs what (and even how) we write.
Anecdotes and examples
For the product that I’m documenting now, I can say with some certainty that users don’t have problems loading data…until something goes wrong. They don’t need a guide that explains which buttons to click (I think everyone knows what “Select file” means). They need to know how to format their data and how to troubleshoot errors. The process of loading a file is the easy part, and something that I can assume my audience knows how to do. But our product has its own requirements for file type and format, and that’s what my audience needs to know.
And I have support tickets to prove it. By collecting more information from customers (through email conversations about the support tickets), I learned that the docs weren’t complete. Based on that new info, I’ve added more examples and troubleshooting tips to that topic.
At my previous company, I was managing a writer who was rebuilding our API docs. We had some people telling us that readers only used the reference tables (and that was supported by web analytics), and that we needed more code samples. But then we had other people telling us that we didn’t have enough introductory content, which was frustrating to new users.
We didn’t have a sense of how many users wanted advanced content over introductory content, or even if they were mutually exclusive. So I pushed upwards, telling my manager that we were working with second- or third-hand information while trying to build a plan for a major project.
I suppose it’s like trying to build a house by using a plan that someone drew on a napkin after looking at the blueprints. The end result might look very much like a house, but it’s likely that the concept of “load-bearing wall” wasn’t fully transmitted.
My manager was receptive, and we worked with the PMs to get us in touch with a couple of experienced (and friendly) users, and a couple who were fairly new (but also seemed friendly).
We had one or two conversations with each group. Not surprisingly, we found that the advanced users wanted us to focus on the reference material and code samples (both were out of date), and the new users wanted an introduction to the API…and code samples.
I’m sure it’s no surprise that anyone working with your API wants A LOT of code samples. And why not? Reusing code is easier than writing it from scratch, even if it needs a lot of customization. It’s the same as a tech writer staring at a blank template or having even an out of date set of docs to start from.
Where do we start?
The key takeaway here is that PMs, sales, etc., are more likely to let you talk to friendly users. This could be long-term users who love your product (your customer success and marketing teams will know who they are), or new users who are very eager to get started (sales and professional services can help with this).
I also found it useful to sit in on customer training sessions. If you’re a tech writer, you’re probably working closely with your training department anyway (if not: What the hell? Where are they getting their content if not from you?). Ask them if you can stand up at the end of the training session and give the students a quick overview of the documentation. But most of all, listen to the users’ questions, watch for areas where they seem confused, or fall behind.
The irony of all of this? My managers were right: I’m spending more time talking to customers, so of course I have less time to spend writing the documentation. Which teaches me that I need to focus: I already know that I can’t document everything, but at least now I’m getting information directly from customers about the docs that will help them the most.
Proactive vs. (or and?) Reactive
But that’s a very reactive approach, and one that can lead to a massive backlog of doc requests. Instead of anticipating what your customers are going to want to know, you’re reacting to their current questions or problems.
The answer is obvious: Hire more writers!
Ok, that might be a bit wishful. I don’t have an answer that will cover every situation: I’m still working it out for myself. But what you will need to do is communicate to your manager, or other higher-ups, that you do need to address your customers’ current questions: It’s great to figure out what they’ll want to know before they ask, but it’s difficult to be a seer. Plus, unless your current product will be obsolete in 3 months, it makes sense to figure out what’s confusing your customers today, and address those issues.
And if your product will be obsolete in 3 months: You have my sympathy. I’ve been there, too.