When Technical Writing Isn’t Writing

When I talk to non-writers about technical writing, or try to sell an employer on my skills, I often run into the idea that writers are kept around because we make things sound good. That isn’t entirely off-base, because writers are often called upon to help with wording (product naming, screen text, error messages) that previously sounded clunky or overly techy. And of course technical writers often collaborate with marketing departments to make sure technical information sounds personable and reflects product branding. Technical writing absolutely should draw on many of the same skills as copywriting and indeed journalistic and creative writing. It should be clear and readable and reasonably compelling to its audience. And technical writing often consists of writing words, or improving words that other people have provided.

Nevertheless, the idea that writers are in tech to “provide verbiage [sic]” or “do a pass on wording” or “make it sound prettier” is misleading and undervalues the main value proposition of technical writing, which is to solve information problems that get in users’ way.

The solutions to information problems are extremely various. The solution to a given information problem is not necessarily “write some words.” It certainly isn’t always “add some words to the existing docs.” If every time a problem like “the customer doesn’t know what an x is” or “this technical procedure is hard to complete from end to end” or “the program is failing in an unexplained way” is presented to you, your solution is “write some words about it,” you are probably not providing as much value to your organization as a writer should.

If, when you are documenting how to do something and you find there are sticky areas in the workflow, you aren’t going back to your test and development teams to talk to them about how those workflows can be made less sticky, you should definitely be doing that. If a developer provides you with a mass of information about how something works, and you aren’t trying to figure out how much of it is valuable and removing parts that aren’t–you are opting out of the supremely valuable activity of questioning information’s need to exist. You can solve a lot of information problems in advance by not publishing information that no one asked for and that doesn’t help anyone. Clutter is a very real information problem.

If you’re not asking how users are supposed to find and use all the answers you are so diligently writing–you should be. When does a user need that information? How will users search all those pages you wrote? Will a trial user and an advanced user be equally likely to look at page 217 of a PDF? Will that error message only be read after a catastrophic failure, when it’s too late? Are the users you are helping likely to already know what you want to tell them?

Should you delete all the information about the 2014 version of the product, in order to improve the likelihood that current users can find what they are looking for? Or is that old information still getting page hits from your most valuable customer? These are typical information problems that technical writers should be solving, and probably not by writing some more pages or removing some passive-voice constructions.

Is a customer’s real difficulty not that they can’t figure out how to install a package, but that Sales hasn’t yet figured out how they can download it from the website to install it? If you are paying attention, you may well be the first person to figure this out, and in this case your job is probably not to write a procedure with a handwavy “get the package” step, but to make sure everyone knows that this is a big problem. You can write a procedure, if it is still needed, after you make sure there is a viable way for a customer to complete an installation.

Technical writing’s value is to increase understanding and make technology more usable, by solving problems that get in the way of understanding and productivity. Many of these problems can be solved with words. (Keeping in mind that words create their own problems, like clutter and technical debt–words are subject to the same overgrowth and obsolescence as code over time.)  But many of them are underlying problems that become evident when you try and make words the bridge that creates understanding. Technical writers should be (and often are) responsible for solving these problems in collaboration with support, development, test, and other teams. They don’t rely primarily on their expertise in the medium of words.

2 thoughts on “When Technical Writing Isn’t Writing

Leave a Reply

Your email address will not be published. Required fields are marked *