The Waste Land: Tech Docs Edition

April is the cruellest month1, breeding
Lilacs out of the dead land, mixing
Memory and desire, stirring
Dull roots with spring rain2.
Winter kept us warm, covering
Earth in forgetful snow3, feeding
A little life with dried tubers4.
Summer surprised us, coming over the Starnbergersee
With a shower of rain5; we stopped in the colonnade,
And went on in sunlight, into the Hofgarten,
And drank coffee, and talked for an hour6.
Bin gar keine Russin, stamm’ aus Litauen, echt deutsch7.
And when we were children, staying at the archduke’s,
My cousin’s, he took me out on a sled,
And I was frightened.8 He said, Marie,
Marie, hold on tight. And down we went.9
In the mountains, there you feel free.
I read, much of the night10, and go south in the winter11.

1This product release is going to be brutal.
2Unless it’s awesome! This time, maybe there will be no typos and the programmers will have told us everything that changed!
3Oh dammit. That module no one has touched since last December.
4Well, perhaps not so little anymore given our diet of breakroom potato chips.
5Quelle surprise. You say you live in Portland?
6Those product managers will talk your ear off. But they paid for the coffee at least.
7No, we don’t have a Lithuanian translation yet, but please check with Sales for an update on our future i18n road map.
8Even in childhood, many technical writers are drawn to low-risk situations and fear lack of control.
9That wild sensation of careening toward the future that is unleashed when you press Enter after typing an ant command.
10Build logs, mostly. But sometimes Kant, or the 50 Shades series.
11Totally springing for the campsite with the showers this year.

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.

Do Tech Writers Need Paragraphs?

It’s a disingenuous question: the answer is obviously yes. Consider, though, how often you write one when you might not need to, and whether a reader might be able to extract the necessary information more quickly.

(No shade meant to the paragraph. I love paragraphs.)

I’m explaining how to do something. Use a list of steps.
I’m persuading someone to do a thing. Sure, you can use a paragraph–also consider bullets, or a table.
I’m creating reference information. How about a table or diagram?
I’m teaching someone a skill. OK, but maybe give them hands-on activities?
I’m clarifying how something works. Maybe, but diagrams are good too.
I’m explaining why something does something. Go for it!  Paragraph!
I’m describing something. OK, but:
1. Make sure you have a good reason to describe it at all!
2. Would a picture or diagram help reduce paragraphiness?
I’m describing a user interface.

You poor thing. Here is some whiskey.

Please don’t write paragraph-length descriptions of a UI. If you can’t have screenshots (lots of reasons why not), your UI is truly baffling, and the UI team can’t incorporate field descriptions on screen, how about a definition list or table?