rtfm*: Technical Writing and ESL, or Doomed! Doomed!

Recently, a friend who knows several languages (one of which is English, but it's not his first language) said that he'd come to realize that his writing wasn't everything he wanted it to be. He wasn't sure if the issues were with his ability as a technical writer or with is command of English. Here's what I wrote back to him.

Let’s assume that you’re concerned about English grammar, first, because that’s the problem with the most wrinkles in it:

English grammar is, of course, a nightmare to get exactly right (and you’re probably more aware of that than native English speakers are). Really, unless you learn the language between the ages of 1 and 4—when you have nothing else to do except learn the language—becoming “perfect” in English grammar is a constant struggle. What makes the problem worse is that these issues seem to leap out at readers of written English in a way that doesn’t happen with listeners of spoken English. I guess that’s just another example of how, in speaking, we pay as much attention to the speaker’s tone of voice and body language as we do to the “words actually spoken”; when we read written material we just pay attention to the words and see grammatical errors that we miss in spoken English. So you can be perfectly happy with your performance as, for instance, an instructor and be unhappy with your performance as a writer.

There’s bad news here: readers overreact to grammatical and spelling errors (“typos”). Readers take grammatical errors as a sign of overall quality (which, as someone who does make grammatical errors, I think is terribly unfair).

However, the good news is that grammatical issues are trivially easy to fix in a written document: delete this word, rewrite this word, re-arrange these three words. Spotting and/or preventing grammatical errors is harder. You can read more English text (some “learning by osmosis” does take place, apparently), take grammar courses, take courses on anything where you submit written material and get the results back with grammatical errors corrected. I have to tell you, though: getting good at preventing and spotting grammatical errors is a time consuming process and you should expect it to take five years of working on nothing but your grammar to become close to “grammatically perfect.” On the other hand, you’re going to be five years older in five years, anyway…

The alternative is to find some native English speaker who will correct your written material. This isn’t hard to do: everyone is an expert in something but everyone seems to consider themselves an expert in English grammar. Depending on your work environment, you're probably be surrounded by people who are dying to be asked to fix up your grammatical errors. Reviewing their changes would also provide you with feedback on the systemic errors you’re making and enable you to start eliminating them, one by one.

Now let’s assume that you’re concerned about effective technical writing: Most people who write technical material assume that what’s important is understanding whatever you’re writing about. That's completely wrong. The most important things in technical writing are:

Audience (who are you writing for): What do they already know, what do they care about, etc.
Scenario: What is the audience going to be using the information for?
Purpose: This has two components—Your purpose: What are you trying to do to (or for) your audience? and their purpose: What does your audience want to achieve? We tend to assume that our audience wants to become an expert in the topic when, often, all they want to do is get their part of the job done as quickly and simply as possible.

The bad news here is that fixing the problems from not doing this stuff right are much harder to fix. If you don't get this stuff right, you'll have material you shouldn't have, you'll be presenting material in a way that won't work for your audience, you'll have material in the wrong place and--the hardest problem to fix--you'll just be flat out missing stuff.

The good news here is that while this set of problems is hard to fix, the skills to prevent this set are much easier to learn. While you can take technical writing courses that last a semester (or even as a three year university degree!) for people with your background/experience that would be overkill. There are lots of good courses/books on technical writing that would tell you everything you need to know (I, obviously, think Learning Tree’s course is pretty good because I wrote it). The Learning Tree bonus site for the course lists four books that I like (again, obviously, I like the last book because I wrote it). I wouldn’t get the first book on the list (Handbook of Technical Writing) as my first book on technical writing--it’s an encyclopedic reference for looking stuff up after you’ve taken a course or read a good book on the subject. Personally, I’d start with the third book: Technical Communication by Burnett. You might find the PDF file on writing effective user manuals helpful: it's sort of "the minimum you should take away from this course".

Reading or read