Previously, I’ve established that the reason Alex Bunardzic likes my writing doesn’t have anything to do with my gender. The real question, then, that Alex meant to ask is: “Why does so much tech writing suck? And why does some writing suck less?” They are genitalia-indifferent, these questions, and well they should be. I will address both.

Does It Really Suck? You Bet Your Hat It Does

But before I wax onwards, I’d like to address the unquestioned assumption behind this thesis: that tech writing sucks.

Is there any question that the state of tech writing is a state of, well, suckitude? Many of us have been there, struggling to keep our eyes open, beating on our skulls hoping that a little percussive maintenance will help the words on the screen or page make sense. We’ve read documents again and again, trying desperately to find the magical missing sentence that will sew up the nagging holes in our understanding—holes which, in their size, inspire metaphors like “big enough to drive the Meow Mix Mobile through.”

But it’s not our fault. We’re not dumb. Put simply, the writing sucked.

Doesn’t sound familiar? If you haven’t been there, you may be one of the very lucky few who can read anything and absorb it no matter what—the more technical, in fact, the better. But trust me when I say the kind of pain I’m talking about isn’t limited to just me and a select group of froofy visual people.

What Qualifies as “Sucking”?

If we’re going to try and be pseudo-scientific about it, the best way to determine if writing sucks is to ask: Does it fail to achieve its objective?

Which, of course, brings us to our next question: What’s the objective of tech writing?

If we think about it, we will inevitably come to the conclusion that ye olde objective will be either to inform or to instruct, or some blending of the two. While these two objectives have a lot in common, including the fact that they begin with the letter ‘i’, they are not the same beast.

Objective A: to Inform

Informing, in this case, means helping to shine a little light on the seeds of understanding in your reader’s head. You’re trying to generously pass on your knowledge, thus informing them of something (anything!). It doesn’t matter whether you’re trying to tell your readers how you modified your Twinkie-smashing robot to pulverize other snack foods, or trying to convince them to use a new feature of your open-source web development framework. Informing deals with facts, background information (hence “inform”), and so on.

Objective B: to Instruct

Instructing is similar to informing, except that it involves doing. If you want to instruct someone, you are trying to teach them a process or action or some such, rather than “just” information.

In Other Words…

Teaching someone how to write a loop is instructing; telling them what loops are and why they should care is informing.

Putting it Together

Many tech writing pieces try to both inform and instruct. In all cases, though, you’re trying to save your reader from having to learn about “it” the hard way, whatever it is and whatever the hard way may be.

I know all this talk about “objectives” and “informing” makes it sound like I’m channeling your 7th grade English teacher. Heck, let’s toss in “rubric” for some good old-fashioned didactic fun! But the simple fact is this: Just because we learned it in school doesn’t mean it’s not true.

At first gloss, it seems like all you need to do to succeed at informing is to include all the facts that you think a person requires to continue along on his merry way; for instructing, you require the steps, and maybe a warning or two against various pitfalls. Unfortunately, this isn’t true—you can create a piece of writing that is component-complete in that regard and still fail in the eyes of the reader. In fact, it’s painfully easy to do, as demonstrated by much of the tech writing out there.

Which brings us to the third question we must answer…

How Does Tech Writing Suck?

So, assuming that the base facts are all there, what constitutes failing to inform or instruct? What kinds of stumbling blocks are we facing here? What mistakes can you make that would ruin an otherwise good collection of facts and procedures?

I’ve attempted to distill the major problems facing technical writing into one, handy little list. Drumroll, please.

The Sins Themselves

The five major sins of bad tech writing (and most writing in general) areeeee…

1. Losing the reader
2. Making the reader feel stupid
3. Failing to stick
4. Being a total bore
5. Not providing much-needed context

Each one represents the outcome of bad techniques—what your reader experiences—rather than a specific behavior or tip you can check off your list. Each one can wreck your piece’s effectiveness all by itself, but like teenagers and prairie dogs, they often travel in packs.

Now, this list is in short, which I realize isn’t really sufficient to explain what I’m talking about and why you should give a hoot (or a prairie dog bark). In long would take pages and pages, and believe me, it’s coming—later. But later isn’t now and there is no time like the present and so here, for your edification, are Amy’s Tech Writing Five Sins in medium.

Sin #1: Losing the Reader

When an author brings Sin #1 down on himself, his reader gives up. Either he literally stops reading the words committed to the piece, or he simply gives up hope of understanding it. This is probably the worst sin, as once you’ve lost ‘em, you’re not likely to get ‘em back—and what’s worse, you might just permanently color their feelings about the technology (or technology in general).

As the famous Gerald Weinberg puts it, authors should always ask themselves: “After exposure to my work, does the audience care less about the subject than they did before?” If the answer is “Yes,” you may have a serious problem on your hands.

Sin #1 in a nutshell: what the heck is this guy saying?, this is not worth my time, get to the point already, lay off the adjectives for god’s sakes.

There are many ways to lose a reader. Sometimes it’s because the reader can’t comprehend what the author has written, and othertimes a reader is lost because he can’t tolerate the author’s style, or the author leaves him without an incentive to continue—maybe not even past the first paragraph.

Sin #2: Making the Reader Feel Stupid

Kathy Sierra has been hitting us all over the head with her mantra “How can we help our users kick ass?” She has been telling the world that if you can generate positive feelings in your user (reader), that’ll rub off on you, your product, or your message. (Emotional Design is an entire book about this idea.)

Unfortunately, the converse, Sin #2, also applies: If you make your readers feel bad about themselves—especially if said readers already kind of suspected they were incapable to begin with—that feeling will rub off on their perceptions of you and your message.

Often the worst perpetrators of Sin #2 do not actually like readers, or get a thrill out of knowing that most of the people who pick up their article/book/what-have-you are “not smart enough” to finish it. If the goal is to disseminate information, this is not a productive outlook. Do not be this person. Seriously.

Sin #2 in a nutshell: don’t point out that I’m stupid (I already think that myself), wow you’re a jerk, maybe I can’t learn this after all, it’s hopeless.

Note: Making the reader feel stupid often goes hand in hand with Sin #1. But as long as she feels stupid AND can continue onwards with the piece of writing, it’s not the same as Sin #1. But it’s still not wise.

Sin #3: Failing to Stick

Being non-sticky means being generally forgettable. The content slides down and out of readers’ brains like spit on teflon. It didn’t (necessarily) made the reader walk away in disgust, or feel dumb, but it hasn’t made a positive impression on him either. Basically, the effect of the writing is net neutral. Kinda defeats the point of writing in the first place. Or, for the reader, spending his time reading what the author wrote. Whoops.

Sin #3 in a nutshell: I was reading this article on…er, something, did I just read this sentence? (over and over)

Note: this doesn’t necessarily mean that a piece is boring (Sin #4). A bit of writing can amuse readers with its sentences and paragraphs and still leave them wondering “What was the point of that article?” at the end. It means that what the author wrote didn’t click with the reader, probably due to a combination of other mistakes, especially a lack of relevancy or context (Sin #5). Or sometimes the author’s inability to get the article to flow, hang together, or gel.

Sin #4: Being a Total Bore

Boringness is the slightest sin, but it feeds the others in a serious way. The more bored a reader is, the less likely it is that she’ll remember anything, the more likely it is that she’ll give up and go away—the ultimate failure.

Sin #4 in a nutshell: Zzzz, the letters don’t even look like words any more, omg if I have to read this I will die

Like the sin of creating negative emotions, being boring is actually more serious than it may sound. With a sufficiently motivated reader, it can be overcome, but making people work at reading your writing is rarely a good idea. As William Zinsser pointed out decades ago in his classic On Writing Well, it’s not about the subject of writing being innately interesting—it’s about the author’s interest in the topic being infectious.

Sin #5: Not Giving Enough Context

Ladies and gentleman, our final item, Sin #5, is probably the most commonly perpetrated sin in the list. It occurs even in writing that is otherwise excellent. If you’ve ever torn your hair out trying to find the secret message between the lines that would actually make the whole thing make sense, well, you’ve experienced Sin #5.

Most commonly Sin #5 occurs when an author doesn’t tell the reader why he should be interested in the piece of writing to begin with. Or when an author doesn’t provide an example of how a certain technique might actually be useful, or a scenario in which a user would benefit from one approach over another.

Sin #5 in a nutshell: yes, but WHY? and this affects me how? how can I use this? I feel like I’m missing something

Sin #5 often leaves the reader having theoretically absorbed knowledge, but completely unable to apply it. At best, a victim of Sin #5 is unsure about the usefulness of what she just read. At worst, the reader glanced at a piece of writing and didn’t see anything that indicated it might be relevant to his life, and skipped it entirely.

Time to Percolate

So, those are the sins. You’ve made it through the list. Hooray! I hope it’s been a pleasant ride for you.

At this point, you may recognize yourself in this list, and you almost surely recognize others in it. And, since you’ve made it this far, I’m going to assume you have an itchin’ to go improve your own writing (and trust me, it can be done)—or, perhaps, to use a printed, rolled-up copy of this article to train the wandering tech author in your life. If that’s true, I’ve done my job. But unfortunately, it’s going to be a little bit longer until I can help you _do_ it.

Note: If you do decide to do the rolled-up print-out thing, please send me pictures.

So far I’ve spent this essay highlighting problems without providing solutions. It’s bad form to do this, granted, but the full-length piece has become incredibly long. Since I hope to actually finish it one day, I’m breaking it up into three digestible stages:

1. Complain a lot
2. ???
3. Profit!

Err. Whoops. Wrong list. Where can I put my face?

I really mean:

1. Describe the symptoms, check
2. Identify the underlying causes (admitting you have a problem…)
3. Attack! (a prescription for betterment)

This is just step one of a three-step process, it just so happens that this first step is the most negative (while the second one is probably the least comfortable).

Chomping at the Bit?

If you don’t want to wait for the next piece to get started on self-improvement (or hitting people with things), here are some things you should read (or use as weapons) in the mean time:

• Kathy Sierra’s Creating Passionate Users
• Weinberg on Writing: The Fieldstone Method, by Gerald Weinberg
• Emotional Design by Donald Norman
• On Writing Well, by William Zinsser
• Words Fail Me, by Patricia T. O’Connor

Your Next Move

So please, bear with—hold the line—watch this space—tune in again. If you’re not a regular ‘round these here parts, consider clicking that jolly little RSS button on the left and keeping your eye out for updates.

And definitely let me know what you think!