Technical Writers Solving My Problem
By Robert Delwood, a Lead API Documentation Writer
Technical writers are part of the solution, if not the actual solution. And I want them to solve my problems. As writers, we need to present complete solutions.
You can almost always tell a CEO’s attitude towards documentation, and hence documentation writers, by looking at how they treat documentation. What I can’t always tell is why they have that attitude.
For example, the other day, someone’s product caught my eye. I downloaded the trial version and started to install it. The installation was interrupted saying their device driver was outdated and to replace it with a new version. But they didn’t tell me how.
They had a potential customer actively loading their product and, as far as they know, ready to buy it and they turned me away. I concluded two things. First, I blame the CEOs. They’ve lost untold sales. They’re acting against their own best interests. But I don’t think anyone is surprised by my saying that. We’re used to disliking CEOs.
Second, I’d like to point to the writers, too. The solution is simply adding those instructions. Add a link or tell me what to do. If the CEO cared a little more, developers could help by checking this value before installation. This should have been caught in playtesting. Because of easily checked glitches like this, there needs to be a new level in Dante’s Inferno for companies that don’t use their own products; dogfooding is the industry term. The point is, there are lots that can be done. No one is looking closely enough at the user experience. We as writers need to do the right thing, even if it contradicts others.
I know some are going to say that the CEO told writers not to do that, that there wasn’t time, or it wasn’t their job. Those excuses may not be good enough now. They’re 1990 status quo attitudes in a 21st-century marketplace. What does anyone think the only outcome could be? Ultimately, the writers are responsible for the user experience. We are the experts and need to push back. Sometimes bosses are wrong. Sometimes CEOs are wrong. Writers owe their bosses not only their industry but also their judgment. And we betray our bosses if we sacrifice it to their opinion.