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 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 descriptive 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?

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. 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 some 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.

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.

NOTES
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.

Why Academics Make Good Tech Writers

Higher education gets ever more expensive and academic jobs ever scarcer, and this year there’s a new crop of essays instructing people who might not have noticed that a Ph.D in the humanities is a very expensive amusement. It is not, however, as described, a life sentence to professional irrelevance. It’s even possible to gain skills there that are highly transferable to the World Outside.

Having become a technical writer 12-odd years ago straight out of a Ph.D program in Victorian literature, I now hire and manage writers for a software company, and while I haven’t yet hired someone who is a direct escapee of the ivory tower, an awful lot of the best tech writers have a Masters or better in something that isn’t a STEM field.

Lots of people assume the best tech writer hire is someone who is a technical person who has learned to write. I’m sympathetic to the idea that the best writers are also tinkerers, but the converse is not always true. The problem here is NOT that engineers can’t write grammatically. The problem is that most engineers are not trained to understand documentation as a set of choices.  Anyone who’s worked on an engineering floor has encountered the bizarre idea that code is an inspiring creative medium that can spawn innumerable variations and effects, but that there is only one accurate way to write a sentence and the main job of writers is to clean up commas in the accurate sentences, possibly adding an adjective or two for color. This outlook is not conducive to producing coherent, readable docs, and it is evident in many of the resumes I’ve received from would-be career-changing programmers.

Academics in the humanities, on the other hand, have a lot of experience with information. Here are a number of things to be said for recovering academics as technical communicators:

1. Academia gives you expert training in unpacking the minds of eccentric monomaniacs. Tech writers who are any good have to be advanced geek whisperers. Interviewing someone obsessed with the obscurities of packet loss is not terribly dissimilar from picking the brain of someone who expects you to understand and care whether those curly bits in Blake’s prints were accidental by-products of acid engraving, or intentional punctuation.

2. Having stuck it out in the academy even long enough to get an M.A., most academics enjoy the company of geeks, even if they are not themselves geeks. (I am. Not all academics are.)

3. Academics have learned to do research. This is rarer than you think in business circles. Presenting multiple sides of a question, documenting what was already discovered and dismissed, providing contextual framework: these are all skills you have if you got anywhere with your humanities work. Does that qualify you to write crisp, relevant instructions? Very possibly not. You may have to unlearn some habits of obsessive completism and smack down your tendency to nest information in dependent clauses, but that’s easier than learning how to notice what information you’re missing and go track it down.

4. Academics are information specialists. Take that 20-page term paper, repackage it as a journal article, turn it into a 20-minute conference presentation, pitch it to the Journal of the Victorian Botanical Novel, rework it as part of a lecture for your survey class: we’ve all done it. We’re used to editing our stuff down and viciously redlining it.

5. (Most) academics are humble about what they don’t know. A Ph.D. is often an apprenticeship in learning about your own ignorance.

6. Most of us have been teachers. If you’ve taught, you have thought about audiences, attention spans, vocabulary level, and how to write headings that will PLEASE GOD MAKE SOME KID NOTICE THE ATTENDANCE POLICY in that sea of text.

7. We pretty much know you can learn anything, if you really have to.  We all had to learn Milton or Linear B or Latin for Reading Knowledge or something else we cared vanishingly little about for a degree requirement. Once, I read Beowulf in Anglo Saxon. And once, I knew all about the TCP/IP stack. I could know about them again and teach other people if you paid me to do that.

Will every academic from the humanities be a great tech writer? No. Some don’t have any technical interests, a few are pompous asses who like sneering at other people’s grammar*, and some are just not interested in being practical. But it’s a lot more likely than the idea that the skills that make you a success at academics are completely non-transferable.

*Their composition students hated them too.