Saturday, May 11, 2013

Why Sam Seaborn is my hero, Or And, C.J., too.

One of my (fictional) heroes, Sam Seaborn, demonstrates how presenting information--technical writing--can be done goodly or badly:



And, while C. J. Cregg isn't actually writing, she's no slouch at gathering, organizing, and presenting information, either:




Reading or read:
Posted by Peter Vogel at 12:00 AM 0 comments Links to this post

Sunday, April 7, 2013

The claim that children don't speak the language well enough (meaning: as well as the speaker) has  been with us always. The claim is that the speaker's generation will be the last to use the language "correctly" usually because of the incompetence of school system.

Of course, whenever anyone complains to be about changes in the language I always ask if they'd rather speak like William Shakespeare. I've now got a better example, but I'll never be able to use it. I just finished "Piers Plowman" (c. 1380) by William Langland which includes verse like this (Jesus during the harrowing of Hell, talking to Lucifer and claiming Adam to be taken out of Hell):

   For the dede that thei dide, thi deceite it made;
   With gile thow hem gete, ageyn all reson.
   For in my paleis, Paradis, in persone of an addre,
   Falsliche thow fettest there thyng that I lovede.
     'Thus yik a lusard with a lady visage,
  Thefliche thow me robbedest; the Olde Lawe graunteth
  That gilours be bigiled-and this is god reson:
  Dentem pro dent et oculum pro oculo.
  Ergo soule shal soule quyte and synne to synne wende.

Even ignoring the differences in spelling, I'd have trouble navigating "With guile thou him get, again all reason" and "Felony thou fittest there thing that I loved." When I said that read Piers Plowman, I meant that I read a translation into modern English (I'm a wimp).

Why can't I switch to saying "Well, do you want to speak the language as William Langland did?": no one but me will 'get it." There's no doubt about it: My life is hell.

And there's a reason that I'm picking on Langland: I found a passage earlier on in Plowman where Langland complains how learned scholars have lost their purity and, as a result, "Grammar, the very foundation of all learning utterly baffles the children who try to study it. If you look carefully, none of our educated people today know how to write verses that scan or produce a decent piece of composition." Just to be clear, what Langland was complaining about was that children had lost the ability to speak Norman French. That was certainly too bad but, as far as Langland was concerned, the real loss was that these children were also losing the ability to speak Latin because it was Norman French which was used to teach Latin. In other words, Langland was complaining that the kids could only speak English.You know, I'm willing to accept that, this time, the kids really weren't as well educated as the parents.

Reading or read:
Posted by Peter Vogel at 10:57 PM 0 comments Links to this post

Tuesday, March 12, 2013

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

Posted by Peter Vogel at 7:33 PM 0 comments Links to this post

Thursday, February 14, 2013

Picking Words, Or P!nk's potty mouth

I picked up The Truth About Love by P!nk (how exactly do you pronounce that exclamation mark?) and have turned into a big fan. One think to be aware of: P!nk's language is frequently...earthy...for want of a better word. When writing songs, the woman swears. A lot.

Fortunately, I find this endearing rather than offputting. Makes me feel hip, young, with-it, and "down with the  young folk." However, I did see a review of one of P!nk's (gosh, that's hard to type, too) albums where the reviewer commented on P!nk's "potty mouth." That reviewer pointed out that P!nk's song "Fuckin' Perfect" came in two versions. The (I assume) original version's chorus goes like this:

            Pretty, pretty please, if you ever, ever feel
            Like you're nothing, you're fuckin' perfect to me

However, there's also the "airplay-friendly" version, which goes like this:

          Pretty, pretty please, if you ever, ever feel
          Like you're nothing, you're perfect, perfect to me

The reviewer's claim was that, since it was possible to rewrite the song to eliminate the word "fuckin'", the swear word was unnecessary and shouldn't have been used in the first poit. But I think the reviewer is missing a key point about how this chorus works.There's some intended discontinuity between the start and the end of the chorus, a movement from a childlike hope to a more adult confirmation coupled with a movement from a polite requst to a strong, personal assertion. For that movement to work there has to be a change. Much of that change is between the first three words of the chorus and the last five words.

The opening of the chorus ("Pretty, pretty please") is child-like/innocent. P!nk (this isn't getting any easier to type) sings that part higher in her register in a more child-like voice than she usually uses. The line-ends in the chorus aren't perfect rhymes ("feel" and "me" rhyme through assonance) which creates some dissonance between the first line and second line all by itself. P!nk sings the last line in an lower register creating more contrast. 

Using "fuckin'" further emphasizes this conflict: it's something that a teenager/adult, rather than a child, would say; it's earthier and more common (in the sense of "lower-class") than the "pretty, pretty please"; "fuckin'" (used in this kind of speech) is an intensifer: it indicates that the speaker really means the following word. While the person being spoken to at the start is implied and not referenced directly, the five words at the end are aimed at "you" making the last five words more personal. The use of "fuckin'" is also more personal speech than the opening line (something that the missing "g" in "fuckin'" also emphasizes by suggesting a particular person's speech pattern). "Fuckin'" also implies sex, again moving to adulthood ("In what way is this person perfect?" "In the fucking way"). That's all lost by removing "fuckin'".

In addition, by repeating the word "perfect" the differences between the start of the chorus and the end of the chorus is lost and, along with that, the movement. The most obvious change is that words are now repeated both at the beginning and the end of the chorus. While there are similarities in sound between the start and the end (the "p"s in "pretty, pretty" and "perfect") those sounds are interruped at the end by the harsher "k" sound in "fuckin'" at the end. Repeating "perfect" makes the beginning and the end of the chorus look more alike--which defeats what's happening in this couplet.

This couplet actually inverts what we normally expect: perfection is associated with a child which is what you once were; this chorus suggests that we have achieved perfection as we moved from being a child to an adult.

I think the reviewer was missing the point: that the airplay-friendly version of the song is a poorer song than the origianl. As a technical writer I don't spend a lot of time worrying about picking exactly the right word but I think Pink (I've given up) did.

If you're interested in seeing Pink  in action, a great place to start is her performance at the Grammys singing her ballad "Glitter in the Air". If nothing else it makes the case that the woman is fearless (and probably does sing better upside down than standing up as she claims). For something a little rockier, I like this live version of "Slut Like You" from The Truth About Love album.

Though, as an unregenerated male, after watching these videos I hope I can be forgiven for thinking about Pink what many men thought about Shania Twain: "All this!?! And I gather she sings, too?".

Reading or read
Posted by Peter Vogel at 2:26 PM 0 comments Links to this post

Thursday, January 17, 2013

Analogies and Metaphors, Or Leading the reader into error


My friend Russ Lewis sent me this quote recently:

“The great thing about metaphor is you can find a little bit of everything in anything. The problem with metaphor is that there is only a so much of anything in everything.”

I think there's a lot of insight in here. This is, for instance, the fundamental flaw in “reasoning by analogy” where someone says is “X is like Y,” then goes on to say “doing A with Y is obviously wrong/stupid/impossible,” and finishes by saying that, as a result, “A should be wrong/stupid/impossible with X, also”. As Russ' quote points out that almost anything can be said (in some sense) to be like something else. Often the comparison is often strained (“how is a raven like a writing desk?”) and people are suspicious of those. But that just means that it’s the analogies that seem plausible ‘on their face’ that are dangerous (“a country is like a big family”—well, no, it’s not and is not in many critical ways) when used to draw a conclusion.

Where analogies are useful are where they make you look at something in a new way. The analogy highlights some feature or purpose of the target that you might otherwise ignore or gives you a new approach to dealing with the target (often the ‘strained’ analogies are the most valuable because they are more likely to give you a genuinely new insight). What makes analogies is that initial “A-ha!” experience where you experience the rush of a new insight: “My gosh, that’s right—and this is useful”. That initial inspiration can then lead you to push the analogy too far and lead you into error.

Metaphors are the most insidious of analogies because unlike similes which are flagged with an explicit “like” or “as” keyword (as in my lake/saint example), metaphors aren’t flagged in the language. In fact, it’s almost impossible to speak English without using metaphors (though many of them are dead). We’ve already spoken of “anything in everything” as if these abstract concepts were somehow packed inside each other like presents in boxes and “insightful” as if we were physically seeing into something that was obscured before (and there’s the metaphor of “understanding” as “seeing”).

There is a defense: For an analogy to be genuinely useful without being dangerous, it’s critical to specify in what ways the analogy works: “a pretty lake is like a saint in that….”). Going on to specify where** the analogy doesn’t work is also a good idea as people don’t tend to think “Oh, I can only use this analogy within the specified limits”—people often need to be explicitly told that “This analogy stops here.”

A trite metaphor is one that gives you an insight that you’ve already had and is, in fact, commonly known.
_______________________________________________________________________________

**notice the metaphor implied by “where” as suggesting physical locations in space—I’m surprised I didn’t talk about “fencing off” the analogy

Reading or read
Posted by Peter Vogel at 1:45 PM 0 comments Links to this post

Saturday, December 29, 2012

Better Design Or, Just don't do it

As I put up the Christmas lights this week, I thought about how much technical writing--especially in user manuals--would just go away if things were better designed for their audience. I'm not suggesting about putting myself out of business...but product design that was better targeted for the product's users would let me spend my time talking about stuff that really does need explanation.

For instance: timers for lights. Timers for lights inside the house support having lights come on and off repeatedly throughout the day. This doesn't make a lot of sense for the inside Christmas lights but these timers are also used to make a house looked "lived in" when the occupants are away for a few days (the timers cause the lights come on in the morning, go off a few hours later, come back on in the evening, etc.)

But, for outdoor Christmas lights, you don't need that much sophistication. All the user wants is to have he lights come on in the evening, stay on for a few hours, and then go off until they come on at the same time the next day. While you can get very sophisticated dedicated devices, I typically get a device design to be used with a block heater (for those of you living where you don't get Canadian winters: a block heater is a device you put in your car's motor to heat the engine block up so that your car will start even in very cold weather). These devices allow the user to set the time that the light is to come on and how long the light is to stay on (or to specify a time to turn off). The current block heaters have reduced the user interface to two buttons (sometimes, just one) and a numeric display (some times two digits, sometimes just one). Some explanation of how to use this UI is required in the accompanying user manual.

But even that supplies more functionality than users need. Christmas lights are used for only a few weeks, at most. Over that time, the sun sets--the point at which the lights should come one--at roughly the same time very day. And, quite frankly, I don't feel a passionate desire to control the duration: anywhere from 4 to 6 hours is fine with me. I don't need as much control as the block heater timers I'm using provide me.

And, somewhere in the world, people who create light-up Christmas decorations have figured this out. For instance, my wife picked up a battery powered Christmas wreath that has a switch with three settings: On, Off, and Timer. Turning the switch to "Timer" causes the lights to come on, stay on for 6 hours, turn off, and come on again in 18 hours (i.e.at the same time the next day as when I first set the switch to "Timer"). This wreath wouldn't work for a commercial firm that needed to turn on multiple wreaths distribute over a large area at sunset on the first day--but it's fine for a home owner who needs to turn a few switches in a single home.

With this design, the instructions boil down to one sentence of instruction and one sentence of reassurance (and I bet that both sentences could be made both better and shorter):

To have the lights come on at the same time very day and stay on for six hours: Turn the switch to "Timer" on the first day at the time you want the lights to come on. As long as you leave the switch at "Timer" the lights will come on at the same time each day and turn themselves off after six hours.


Reading or read


Posted by Peter Vogel at 3:59 PM 0 comments Links to this post

Wednesday, December 5, 2012

Word Choice and Grammar or, It's not a problem


I was teaching my technical writing course for Learning Tree last week and we had a young woman in the class from China. When we got to the final exercise--about 600 words aimed a recent immigrant on how to survive a Chinese wedding party dinner--her document contained numerous grammatical mistakes (mostly around plurals) and at least one unfortunate word choice (in suggesting that guests wear formal outfits, she suggested a tuxedo for the man...and a nightgown for the woman).

It was a great document to end the course with because (a) it gave us a chance to laugh at ourselves and (b) it made a great point that I keep hammering away on in the course: those errors don't really matter. I'm not denying that they needed to be fixed--a final pass by an idiomatic English speaker was definitely required. But the changes were trivial: add an "s" here, change "nightgown" to "evening gown." The content was spot on, there was an excellent balance of given and new, the organization was great. All the things that would require real time to fix or force a significant rewrite were taken care of.

What's too bad about this is how readers react to the errors that were present. Readers take the presence of the kind of trivial errors that were in this document as measures of overall quality. So much poorer documents than the one that this student produced would be more highly valued than this document. It emphasizes that the final pass through a document has to be a proofing pass to remove these kinds of "dissatisfiers."

I suspect, though, that the reason that I feel this is so wrong is that I am so bad at proofing my own work (so bad that no one would ever ask me to proof someone else's work).

Reading or read
Posted by Peter Vogel at 2:49 AM 0 comments Links to this post
Subscribe to: Posts (Atom)