rtfm*

New York Streets, or The Origin Names

2012-01-19T11:57:00.000-05:00

I was in New York a few weeks ago and it made me think about names. I was walking down Broadway, for instance, which was originally a "broad way." You can imagine how that worked: "You turn left onto another street--well, really it's just a broad way" or "Turn left--you'll know it: It's quite a broad way" turns into "Turn left on the broad way" and, finally, "Turn left onto Broadway."

The same is true of Wall street--"It's the street with the wall" becomes "It's the wall street" and then "It's Wall street." Almost every English town I've visited not only has a High street but makes it easy to identify the next street added because every town has a street called New street.

The same process leads from "Make me one of those things that the Earl of Sandwich has...but with more mustard" to "Make me one of Sandwich's things" to "Make me one of those Sandwich things" to end with "Make we a sandwich."

I remember the kick I got out of staying at a hotel in England and walking to my client's site every morning. I went past the Royal Military Museum (or whatever it's called) which was once Bethlehem Hospital: Bedlam. It was very cool to see, every day, the visible expression of our language's growth.

Reading or read

Five Fists Of Science by Matt Fraction and Steven Sanders
Moby-Dick in Pictures: One Drawing for Every Page by Matt Kish
Supergods by Grant Morrison
Devil Sent the Rain: Music and Writing in Desperate America by Tom Piazza
Top Ten: The Forty-Niners (Top 10) by Alan Moore and Gene Ha
Joe Simon: My Life in Comics by Joe Simon
The Quantum Thief by Hannu Rajaniemi
Chardin: An Intimate Art by Helene Prigent
St. Trinian's: The Entire Appalling Business by Ronald Searle
What is a Print? by Sarah J. S. Suzuki
A Treasury of Tom Thomson by Joan Murray

Words for Christmas, or Merry Christmas, anyway

2011-12-26T14:54:00.000-05:00

About this time of year, I see articles and postings about how people are bravely (and defiantly!) going around saying "Merry Christmas." The only problem is that no one has ever suggested that they shouldn't wish everyone they meet "Merry Christmas." It reminds me of a Tom Lehrer bit where he talks about people getting up in coffeeshops to bravely sing folk songs about all those things that everyone else in the room is against...like peace, love, and brotherhood.

The closest anyone ever came to do suggesting that "Merry Christmas" wasn't always a good idea was various organizations (not individuals) that represent or deal with a diverse body of people (WalMart, your government). Those organizations, rather than respond to every one of their constituents, adopted a neutral greeting (typically, "Happy Holidays"). People who, by default, had always had their way before were now incensed because they weren't being treated as if they were the only people in the world.

It would seem obvious that you can't have the government collect tax dollars from citizens of diverse faiths and then use that money to enforce your faith. Nor does a commercial organization, with potential customers of diverse faiths, want to appeal to just one segment of those customers. In both cases, rather than represent all faiths, the organizations have decided to represent none--which is too bad but (I guess) a choice made from efficiency.

If I was a generous person with respect for others I would make an attempt to learn about the faith of the people I was interacting with and, at the appropriate time of the year, wish them "Happy Hanukkah", or "Joyous Id." Embarrassingly, I don't make that effort and assume that others are just like me. Refusing to recognize that other people may differ from you and insisting, instead, that they be just like you and serve your needs is, I think, the base of all rudeness.

As part of this discussion, we'll get people who, rather than present their statements or actions as rude, claim they are taking a stand against "political correctness": What they are about to say is something brave and they are, somehow, defying authority. In fact, it always turns out that they are about to say something that asserts their special position in society, serves them before others, and claims some special privilege that they should get and others should not.

However, none of those things are either (a) Christian or (b) appropriate at Christmas. So, as Christian celebrating Christmas--Merry Christmas. And for all my friends who are practicing their faith--Happy Holidays!

Reading or read

Divine Justice (abridged) by David Baldacci
The Absolutely True Diary of a Part-Time Indian Collector's Edition by Sherman Alexie
Vets Might Fly by James Herriot
All Things Wise and Wonderful by James Herriot
Lost & Found Sound and Beyond by The Kitchen Sisters
Vacuum Diagrams by Stephen Baxter
Lord Tyger by Philip Jose Farmer
Hyper Real: The Passion of the Real in Painting and Photography by Brigitte Franzen and Susanne Neuburger
The Real Charlotte by Martin Ross
Freedom: A Novel by Jonathan Franzen
Comedy in a Minor Key: A Novel by Hans Keilson
Four Corners on Main Street by Paul Ross
Top Ten, Book 1 by Alan Moore and Gene Ha
Criminal Vol. 2: Lawless by Ed Brubaker

Taking Suggestions, or Pretty things! Pretty things!

2011-12-04T05:45:00.000-05:00

I sometimes wonder if I have any actual ideas of my own. Whenever I have a problem with, well, practically anything, but also with course development, I go around discussing it obsessively with everyone I can find. Of course, some of the people that I inflict my concerns on suggest solutions.

Most of those solutions I can't use. There may be logistical constraints (time, usually--the idea would devote more time to a topic than I think it's worth) or conceptual (for instance, incorporates material outside of the course's mandate). But, sooner or later, someone comes up with an idea that I can use and I (shamelessly) track it down and incorporate it into the course.

I do have ideas of my own (and about 25% of them work right away and another 25% work after significant rethinks). But looking back over my courses, I'm not sure that the best ideas didn't come from all the people around me.

Reading or read

Running Away by Jean-Philippe Toussaint
Paper Shadows : A Chinatown Childhood by Wayson Choy
Jack Chambers: Light, Spirit, Time, Place and Life by various
Mr. Fox by Helen Oyeyemi
Miss Marple Investigates by Agatha Christie
Howl's Moving Castle by Diana Wynne Jones
Stargirl by Jerry Spinelli
The Westing Game by Ellen Raskin
Strung Out by Sara Paretsky
Not Yet: A Memoir of Living and Almost Dying by Wayson Choy
The Swimming-Pool Library by Alan Hollinghurst

Working with SEO, or Sometimes virtue is rewarded

2011-11-13T10:05:00.000-05:00

I've been doing some search engine optimization (SEO) work for a local law firm (our goal: Move the firm from the 31st position in a specific Google search list to the first position).

When I was first involved with SEO, it was all about programming tricks--using meta tags, building circles of self-referential sites, and so on. What's encouraging is that, this time, it appears that the current crop of search engines have improved to the point where they either ignore or discount those games (and, apparently, actively devalue sites that engage in them). Instead, the current crop of search engines actually reward great content that others value.

We have two advantages on this project. First, one member of the firm has the ability to turn out great content that's relevant to the site. We should be able, in a relatively short period of time, to build up an inventory of content that people will be able to find. On previous projects, I've been responsible for learning about the organization, figuring out what would be valuable to the audience, and then generating the content. This time, I may have an advisory role, but the firm can handle it all in-house.

The other advantage is that the firm, it turns out, has built their site using WordPress. I'm not getting much chance to use my programming skills but it means that it's reasonable for a firm member to become an expert in extending and maintaining the site (the disadvantage is that I'm having to educate myself in "the way of the WordPress"). Again, once I move on, the firm will be able to control it's own destiny.

Really, there's only one part of the project that's going to be challenging--we'd like to short-circuit the process of people finding the site by encouraging others to link to it. We have at least one member of the team that may be in a position to do that but we'll have to see how many members of the firm we can drag into this process.

Reading or read

The Best Laid Plans by Terry Fallis
Traits and Stories of the Irish Peasantry Volume II by William Carleton
Gotham Central Book 3: On the Freak Beat by Greg Rucka, Ed Brubaker
Gotham Central Book 4: Corrigan by Greg Rucka, Ed Brubaker
Shiloh by Phyllis Reynolds Naylor
Verses and Versions by Vladimir Nabokov
The Group of Seven and Tom Thomson by David P. Silcox

Building Trust, or You'd think that I'd know better

2011-10-30T21:25:00.000-04:00

One of the interesting things that happens over a multi-day course is that a certain level of trust builds up between the instructor and the participants. It could just be an example of the Stockholm syndrome: The captives begin to identify with their captor.

One result of that effect is that, when participants evaluate the course and the instructor, it's very unusual for the instructor to get a lower score than the course. When the participants aren't happy, they blame the course rather than blame the instructor. This is obviously a good thing for the instructor.

What this also means, for the instructor, is that there are things you can do on the last day of the course that you can't do on the first day.

I got a measure of this effect, to my detriment, on the course I taught last week. The course I was teaching incorporates several videos demonstrating bad practice. One video has two people (one of them a blonde woman) acting very badly. In debriefing this video, I'm fairly harsh about the behaviour of the two people. Because I don't expect class participants to catch the name of the characters in the video I refer to the woman as "the blonde."

I've never had a problem with this approach until my last teach. The course had been revised and this video was moved up to the first day from the last day. Not only did I lack the trust that three days together builds up but, exacerbating the situation, by day 3 the participants have had enough training to recognize most (or all) of what the characters to do wrong. I failed to recognize the looming problem and did the same debrief for the video on day 1 as I did when it ran on day 3.

Without the trust that gets built up over three days of class and without the training, I must have come across as a brutal madman. By referring to one of the characters as "the blonde" I must have came across as a sexist brutal madman.And, in fact, I discovered that I had deeply distressed at least one participant.

The only reason that I know this is that the participant came up to me at the end of the class to discuss how upset she'd been, which I appreciated. Without her specific feedback, I would never have figured out how I had put my foot in it.

And, thanks to her, I got a good measure of how much trust does get built up over a week of teaching.

Reading or read

Inverted World by Christopher Priest
Kepler: A novel by John Banville
The Newton Letter by John Banville
Two Generals by Scott Chantler
Tangles: A Story About Alzheimer's, My Mother, and Me by Sarah Leavitt
The Road to God Knows... by Von Allan
Beauty by Sheri S. Tepper
Sherlock Holmes, Vol. 1: The Trial of Sherlock Holmes by Leah Moore, John Reppion and Aaron Campbell

Words, words, words, Or Does anyone think about these things?

2011-10-02T08:34:00.000-04:00

Watching TV ads I often wonder if anyone stops to think about what words they use. I assume they must, but...

I have two favourites in this area. One is from a few years back and it was for a new bra from Victoria Secret. The tag line for the ad was "A bra so well designed, so well made, it could only be called....Vapris." Ok, I don't remember what the last word was--but my point is that it was a made-up word (a nonce word, for the initiated). Any combination of letters could have followed "only be called..." It could have been "Gork", or "xyzzy", or "Fred."

My latest fave is an add for KFC which begins "Other restaurants make chicken nuggets. What part of the chicken is the nugget?" It then goes on to say that "We make popcorn chicken." OK. And what part of the chicken is the 'popcorn'? A perfect example of moving the problem around but not actually solving it.

Reading or read:

Gotham Central Book 2: Jokers and Madmen by Greg Rucka, Ed Brubaker and Michael Lark
Island of the Blue Dolphins by Scott O'Dell
Hicksville by Dylan Horrocks
The View from Saturday by E. L. Konigsburg
Messenger by Lois Lowry
Red Mars by Kim Stanley Robinson
The Broom of the System: A Novel by David Foster Wallace
The Best of Gene Wolfe: A Definitive Retrospective of His Finest Short Fiction by Gene Wolfe
Snow Crash by Neal Stephenson

Braincramps in Dealing with the Audience, or I know better than that....really

2011-09-11T20:04:00.000-04:00

I've been beavering away at the Service Oriented Architecture course I'm working on for Learning Tree and just taught the latest version of the course in New York city. I think that this version is the best so far but, sadly, it provided a great example of how I commit blunders that I would spot in a second--in any one else's work.

For instance, the audience for this course is a combination of business people and developers (I know this). The course focuses on what matters to both groups: making sure that you're working on the right things (I know this also).

However, that didn't stop me from dropping in six slides of low-level technical detail that was only sporadically connected to something that the audience would find interesting. I probably spent as much time answering questions about "How do I use this material?" at the end of the section as I spent going through the section. But the worst part was watching everyone's eyes glaze over as I marched through the slides. That horrible thought: "I'm losing them."

Any way, I went back and restructured the material around what matters to the audience: How do I pick the right technology for me. I also replaced some of the low lever detail either with content that the audience would value or, better yet, with nothing. And I then discovered, now that the section made sense, that it formed the perfect introduction for the chapter that it's part of.

Life's like that. At least it was only six slides rather than the whole course (that was my first version of the course).

Reading or read

Mockingjay by Suzanne Collins
Some Experiences Of An Irish R. M. by Edith Somerville and Martin Ross
The League of Extraordinary Gentlemen Volume III: Century #2 1969 by Alan Moore
The Untilled Field and Other Stories by George Moore
Traits and Stories of the Irish Peasantry, Volume I by Carleton, William
The Best of Myles by Flann O'Brien
Claes Oldenburg: An Anthology by Marla Prather
String Quartets of Beethoven by Professor Robert Greenbery
Wake in Fright by Kenneth Cook
Autobiography of Red by Anne Carson
Three Exemplary Novels by Miguel De Unamuno
In Zanesville: A Novel by Jo Ann Beard
Hiroshima by John Hersey
The Collapsium by Wil McCarthy

Selling from the Reader's Point of View, Or Whipping up enthusiasm

2011-08-20T11:57:00.000-04:00

Unfortunately, when technical writers or instructional designers talk about their documents or courses, they often do it from the point of view of someone who has read the document or taken the course. Often this turns into the point of view of someone interested in improving their knowledge of the field rather than the point of view of a practitioner: someone interested doing something useful in the field.

This matters for an important reasons: The description of your document/course often controls who many people actually ever read it or take it. Very few people read technical documents or take technical courses for fun. Most readers/participants are there because they need help. At the very least, then, when describing a technical document or course, the author should try to whip up some enthusiasm for the material covered.

Now this may sound like I'm suggesting some kind of phoney marketing ploy but that's not my intent. The surest away to encourage interest in a technical document or course is to talk about what interests the potential participant or reader--remembering that the audience for this description hasn't yet read the document or taken the course. You need to describe your document or course in terms of what it will enable the reader/participant to do that they weren't able to do (or do as well) before.

In other words, a description of a technical document or course should be a description that talks about what the audience wants to know, of what keeps the audience awake at night, of what will have value for the audience.

I saw this recently in a brochure page describing a Learning Tree course. The author of the brochure showed admirable restraint, appropriate for someone already part of the field and secure in the field's knowledge. However, the bullet points that described the course objectives seemed specifically designed not to connect with the audience. For instance, the first bullet was:

Perform key functions of the business analyst by applying a solid business analysis framework

I find it difficult to believe that anyone wakes up in the morning thinking "Gee, I wish I could perform the key functions of the business analyst" or lies awake at night worrying that they don't have "a solid business analysis framework." People worry about very specific things, not generalized issues like "key functions" or want generalized help like "solid framework."

In fact, this is a bullet that's interesting only to someone who already knows that the key functions in the field are and, while they have some skills in the area, want to solidify their knowledge into some kind of structured knowledge. These are the goals of someone primarily interested in improving their knowledge of the field (solidifying, getting a framework), not in doing a better job at work ("performing"--a very general term--references the even more nebulous "key functions").

So, what do potential readers/participants care about? This particular course was aimed at business analysts who are expected to determine the current and potential problems for an organization, define a list of potential solutions, help the organization pick a solution from that list, and then support implementing the chosen solution (which might be an amalgam of some of the proposed solutions).

The first thing that a potential business analyst would worry about, then, is their ability to identify the organization's problems. If the analyst gets that wrong, all the subsequent work is misdirected and, when the "real" problems turn up, the organization will be unprepared. So a bullet that would describe a course that's interesting to someone who doesn't already know the material would be something like this:

Perform a key function of the business analyst: Identify the organization’s key problems

This is, of course, just a first cut (I'd love to replace the generic "Perform" and "Identify" verbs with something more specific). But, I imagine, it would be something that potential reader/participant would read and say "Yes! I want to know that! I need to know that."

Reading or Read

Speak by Laurie Halse Anderson
Changeover by Margaret Mahy
Gathering Blue by Lois Lowry
The Monk by Matthew Lewis
Road to Brightcity by Máirtin Ó Cadhain
Canon Alberic's Scrap-Book by M R James
The History of Science Fiction by Adam Roberts
The Fifty Minute Mermaid by Nuala Ni Dhomhnaill and Paul Muldoon
Myth, Legend, and Romance: An Encyclopaedia of Irish Folk Tradition by Dáithí Ó hÓgáin
Doctor Copernicus by John Banville

Matching Scenarios, or Cooking Sainsburys

2011-08-07T13:42:00.000-04:00

I focus a lot on the audience but, for technical writing, scenario is the second most important input to creating a genuinely useful document. In technical writing, "scenario" describes the situation in which the reader will use the information and, recently, I just had an otherwise excellent piece of technical writing fail on this issue.

Some background: My wife and I are on another house swap, this time into Northern Ireland. When we're in the UK, I cook at least one meal for us by buying a package meal from Sainsburys or ADSO. These are an Indian, Chinese, or Thai meal-in-a-box. Typically, there are four or five courses and taste fine. What I like is how easy it is to cook the meal: You set the oven to some temperature and just feed packages of food into the oven at regular intervals. So there's your audience: someone clueless in the kitchen.

The instructions for the Chinese meal I cooked last night were:

Overall cooking time (cooking from chilled): 30 minutes

Set oven temperature to 175 degrees Celsius
Puncture the cover for the rice and the chowmein and place in the oven
After 5 minutes, remove the battered chicken from their container and put on a baking sheet in the oven
After 10 minutes, remove the vegetable rolls from their container and put on a baking sheet in the oven; put the container with the sweet-and-sour sauce in the oven

And that's the end. If you work through the scenario, you realize at this point (or, at any rate, I realized at this point) that you don't know when to take the meal out of the oven.

You can, of course, figure it out. The overall cooking time is 30 minutes and the second set of containers went in at the 15 minute mark, so the meal comes out in 15 minutes...except I hadn't bothered to notice the time when I put the meal in.

What I had noticed was the time when the second component should go in. And, after putting that component in, I noted the time to put in the third component. You might assume that I would have set the timer on the oven to 30 minutes when I put the first component. I didn't. But, if I was going to set the timer to anything when I put the meal in, I would have set the timer to 5 minutes so that it would remind me to put in the second component.

If the person writing the instructions had an actual audience member (like me) try the instructions out--someone who's idea of cooking is warming things up--then they would have added the fifth and final instruction:

5. After 15 minutes, remove the meal from the oven.

Reading or read

At Swim-Two-Birds by Flann O'Brien
The Brazen Serpent by Eiléan Ni Chuilleranáin

Expectations, Or Keep the customer satisfied

2011-07-29T02:29:00.000-04:00

But when it comes to writing courses (especially for Learning Tree International who I've done most of my course development for), I've noticed that I worry a lot about "participants' expectations."
Learning Tree makes every attempt to "set participants' expectations appropriately" as early as possible. On the company's website and in the course catalogs that are distributed to customers, Learning Tree describes courses in some detail: Who should attend, what topics will be covered in the course, what activities participants will be involved with. Sales staff who talk to customers (and customers themselves) also have access to the "Q&A" sheet for the course which lists some of the more common questions that customers have and provides answers. When participants arrive in the classroom, the course always begins by laying out the course's objectives and list the chapters that make up the course. Learning Tree has always been willing to make changes to the course descriptions to help ensure that, when participants show up in the classroom, they will get what they expect (even if that means limiting the number of customers who might be interested in the course).

Nonetheless, at the end of a course participants sometimes tell us that they had expectations that the course didn't satisfy.

My advice in these situations is always the same: Give the participants what they want. It's just easier that way and, besides, these are paying customers who should get what they believe they're paying for.

But....there are three issues with this approach. There are some cases where the course author is confident that there is something that participants MUST be taught. In that case, the author has to devote some time to convincing participants that they should value this material. The only way to do that is to tie the author's topic to things that participants do value (and know they value). Of course, there's the possibility that the author will fumble this, that the instructor won't convey this well in the classroom, or that the material will be tied to things that participants don't value. And, of course, the time spent on making this connection is time that can't be spent on the topics that participants know they want. So I always question the belief that a topic must be included even if the audience is deeply uninterested. The key question here, as always, is: What will participants do differently after hearing this information?

The second issue is when the expectations among the participants are not homogenous: When the course is taught there are often multiple audiences in the room (what, at Learning Tree, we call the "split audience" problem). While some authors try to satisfy all of the audiences in turn (a little bit for this audience, a little bit for that audience) my impression is that doesn't usually work. The right answer is, instead, to concentrate on only those topics that all of the audiences in the room value. There may not be a course there or, if there is, it may be a very short course (the audiences don't hold much in common) but that's your best hope for a course that the participants will value. You can, at best, once or twice a day, spend five minutes on a topic that's of interest to only one of the audiences (if, for no other reason, then to build up credibility with that audience). Any more than that and you risk the other audiences feeling that their time is being wasted.

The third issue is the most interesting: When the audience has no well-defined expectations. This is especially true of courses covering new, "hot" topic or courses built around buzz words. The first thing to recognize is that there may be no course there: that the topic for the course is "unwriteable." Think, for instance, of a course around "driving": driving a car, a horse, a motorcycle, a plane, a submarine (at Learning Tree that mythical course would be called "Driving: A Comprehensive Hands-On Introduction"). This course is, I would say, plainly unwriteable--the audience interested in driving the car is going to be bored rigid in the sections that address driving a submarine; further, there's no common material that would be of interest to all the participants.

If the course is writeable then the solution for "fuzzy expectations is to spend the initial stages of the course developing a set of expectations with the participants. Obviously, by the time that the course is being taught, the course is already written. So the initial stages of the course must develop a specifici set of expectations: ones that the rest of the course satisfies.

You can't, unfortunately, tell participants what they should be wanting so this is best done interactively.What works best is to present the participants with a series of problems that the participants believe they will face (at work or in life). These must also be problems that the participants want solutions for. From that, you can help the participants develop a set of expectations around what would solve those problems. Your course can then deliver those solutions which, presumably, the participants will now value.

Reading or read:

Catching Fire by Suzanne Collins
A Star Called Henry by Roddy Doyle
The Book of Durrow by Bernard Meehan/Ciaran Carson
Beowulf: A New Verse Translation by Seamus Heaney
Pocket History of Irish Writers: From Swift to Heaney by A. Norman Jeffares
A Snail in My Prime by Paul Durcan

Homely vs. Homely, Or Crossing the water

2011-07-18T05:58:00.000-04:00

I think I've spoken earlier about a friend who told a mildly scandalous story in England that he had heard in Canada and discovered that "fanny" meant something more salacious in England than it did in Canada. I got caught out once in England by commenting that I was willing "to spend a penny" to save some larger amount of money ("spend a penny", it turns out, is a euphemism for peeing).

Here in Ireland, we're watching a television show about flipping houses and heard someone comment that, after renovation, the new house was "homely." Back home in Canada, "homely" means anything from "plain" to actually "ugly." The term we'd use in Canada for a place that felt like a home would be "homey"--what a difference an 'l' makes.

So what is a technical writer to do? Given the pitfalls, for any document that will be read by someone from another country, the only safe thing to do is to have some native speaker from that country read your document. There's simply no way that you can catch all the potential differences.

Reading or read

Madam Crowl's Ghost and Other Stories by Joseph Sheridan Le Fanu
The Captains and the Kings by Jennifer Johnston
Books of Blood Volume One by Clive Barker
Hero of Lesser Causes by Julie Johnston
Fly Boy by Eric Walters
Night: A Novel by Edna O'Brien
The Sea by John Banville
The Beauty of the Husband: A Fictional Essay in 29 Tangos by Anne Carson

Missing Commas, or Where's the fun in that.

2011-07-10T20:09:00.000-04:00

I have fond memories of David Frost's show "The Frost Report". The best part of the show was, for me, the word play. I still have fond recollections of "Strange Parts of the Human Anatomy" as described in the sentences "I wonder who's kissing her now?" and "The love of London remains in her yet" (my favourite). (I'm sure the joke is older than the show).

The joke depends on taking "her" as the possessive and the following word as the possessed noun (rather than taking "her" as the object of the previous preposition or verb and the following word as a duration term). The joke works better when spoken (as on the show) and disappears completely with the proper punctuation: "The love of London remains in her, yet", "I wonder who's kissing her, now."

What got me thinking about his was passing a sign outside a law office that said "Welcome To The Team Lesley." I spent two blocks trying to figure out what a "Team Lesley" was before I figured out where the comma was supposed to have gone.

This year at the cottage, it was all genre books--I read a whole bunch of books I've been meaning to get to for the whole year.

Reading or read

As I Crossed a Bridge of Dreams: Recollections of a Woman in 11th-Century Japan by Sarashina
The Travels by Sir John Mandeville
Lankhmar Book 1: Swords And Deviltry by Fritz Leiber
The Ceremonies by T. E. D. Klein
The Franchise Affair by Josephine Tey
Man Called Horse (Originally: Indian Country) by Dorothy Johnson
The Branch and the Scaffold by Loren D. Estleman
Aegypt by John Crowley
The Walking Dead, Book 1 by Robert Kirkman, Tony Moore, Charlie Adlard and Cliff Rathburn
Ares Express by Ian McDonald
Julian Comstock: A Story of 22nd-Century America by Robert Charles Wilson
Red Dog, Red Dog. Patrick Lane by Patrick Lane
Ella Enchanted by Gail Carson Levine

Generating New Words or, Unsubtitle

2011-06-26T19:52:00.000-04:00

In the same way that "evolution" is a creation machine that keeps creating new forms of life (look around you), I'm always impressed at how language is, itself, a creation machine that generates new language (just listen).

I often read about "verbing" nouns--"gift" becomes "gifted," for instance. Less often discussed is how verbs become modifiers. For instance, the verb "install" not only moves from being a verb but also to being a modifier: I see "install package" or "install utility" as often as I see "installation package."

But Wait!, There's more! In a tweet last week, I commented on how "un" can be tacked onto almost anything (I saw a commercial that referred to "unlevel concrete"). So, from "install" we get "uninstall" as both a verb and a modifier: These days, we can "uninstall anything" and we can have an "uninstall button" or an "uninstall package."

Some modifiers move almost immediately become nouns--brand names, for instance. Technically, people should buy a "Macintosh computer" but most people, in fact, we'll tell you that they're going to buy "a Mac." Can it move to a verb? Can we "Mac" something?

Reading or read

When You Reach Me by Rebecca Stead
Fever by Sharon Butala
Of This Earth: A Mennonite Boyhood in the Boreal Forest by Rudy Henry Wiebe
Lucian Freud: The Studio by Cecile Debray
Cockroach: A Novel by Rawi Hage

Phrasal Verbs or, Showing how smart you are

2011-06-18T11:22:00.000-04:00

English has many multi-part verbs (e.g. "take in", "take out", "take up", "take down"). Apparently, these phrasal verbs are one of the more unusual features of the English language. I'm told, for instance, that English-as-a-second-language learners have to struggle with these forms. What makes it worse is that we tend to convert these phrasal verbs into nouns or modifiers--food I that I "take out" becomes "takeout" food, for instance; I "lay out" the page to generate the page's "layout."

Which leads to people confusing the verb form with the noun form. Just yesterday, I saw "layout" used as a verb, for instance (but, of course, if enough people make this error often enough, "layout" will become a verb). Part of the issue is that this is an error that's only possible to spot when written down--the problem doesn't exist in spoken English.

So phrasal verbs provide a great opportunity for you to show how smart you are. Spotting and commenting on this error shows that you are much more knowledgeable about the English language than your friends are (assuming you have any*).

Reading or read

Selected Poems by Al Purdy
The Town: A Novel of the Snopes Family by William Faulkner
Painters Eleven: The Wild Ones of Canadian Art by Iris Nowell

*Winston Churchill reference

The Philosophy of Language, Or Ordinary is good enough for me

2011-06-07T11:01:00.000-04:00

I rearranged my bookshelves a month or so back and found a bunch of books that I bought while in university that I hadn't (ever) gotten around to reading. Part of that "rearranging" was actually purging but I hung on to a few books in the area of 'ordinary language' philosophy.

For the uninitiated (and let's remember that I don't really know what I'm talking about here): Ordinary language philosophy approaches many philosophical problems as "muddles" caused by misuse of the language. For instance, a great deal of philosophical discussion revolves around the nature of "reality." A die-hard ordinary language philosopher would say that we should first begin by looking at how the word is used in "ordinary language"--at the day-to-day use of the word. So we say something like, "Yes, but--in reality--it doesn't work that way." By building up all the different uses of the word (and some of those uses have little or nothing in common with other uses), we can see what the word "means". And, it may turn out, that we don't ever use the word "reality" to refer to some external, shared experience. Instead, we use it as a kind of modifier to indicate that something is practical. A philosophical inquiry into what "reality" is only exists because we are using the word in some peculiar way that the language doesn't support.

The other side of ordinary language philosophy is that some problems exist solely because of some peculiarity in our language's syntax. Imagine that our language's syntax required us to say, rather than "Nobody is in the room", but that "Mr. Nobody was in the room." Someone might launch an entire school of philosophy in the search for "Mr. Nobody". I would see that kind of muddle perpetuated in the phrase "my mind", which looks similar to "my car", "my DVD player" and so on. This leads to a philosophical discussion of who is the "me" that is separate from my "mind" and what is the "mind" independent of any particular person. The relationship between "me" and "my mind" doesn't exist: I am my mind and my mind is me though the language makes it appear that a distinction exists. The phrase "My mind" is more like "my voice" than it is like "my car."

Now this doesn't have much to do with technical writing, except that the exploration of language always helps me to understand my tool better. I just finished, for instance, "How to Do Things with Words" which points out that statements we make aren't always "true" or "false" (e.g. "Go and get me the hammer" isn't true or false). For instance, one way of looking at statements is to see them as performing an action rather than asserting facts.

For instance, in a marriage ceremony when I say "I do" I am--by saying those words--performing an activity; when the ministering official says "I pronounce you man and wife", that official is performing the marriage activity. Similarly, when a referee declares a penalty in a game, the words that the referee utters can be classed among those utterences that "do something" just by being said (which gives the book one of the puns embedded in its title: "How to Do Things with Words"). If you don't say the words, the activity doesn't happen.

I certainly didn't go into ordinary language philosophy deeply back in university to actually appreciate/understand it. But it did leave one lasting mark on my life: the phrase "I don't think that's a meaningful utterance." It's not something that I get to use often but it's damn useful when I do get to use it. And, when writing, I try to apply it to everything I write: Is this a meaningful utterance? Some criteria I use:

The things it refers to actually exist. I frequently hear pundits commenting on contentious issues by saying things like "America wants ...." or "America expects..." To what does the word "America" refer in that sentence? Given that the issue is contentious, obviously not "everyone who lives in America" or even "American citizens."
The sentence accomplishes a useful purpose for the audience. For instance, when a commercial for a diet as being rated as "the top diet" my first question is "What does 'top diet' mean?" Does it mean 'Most effective in losing weight quickly'? 'In keeping weight off ? 'Works really well for its target audience'? Works for everyone'? The sentence may be useful to the person saying it but doesn't do much of anything for the audience.
The sentence is being spoken in the appropriate scenario and to the appropriate audience. For instance, saying "I do" if you are the officiating minister doesn't work; saying "I now pronounce you man and wife" if you are not the officiating minister or, even if you are but are in the wedding rehearsal, doesn't count either. Is what I'm saying actually relevant to the people reading it? Is this the right forum for saying it?

It's especially fun to listen to elected officials and ask how many of the sentences they utter are actually, in any meaningful sense, meaningful. The percentage sometimes approaches zero.

Reading or read

Selected Poems by Fleur Adcock
How to Do Things with Words by J.L. Austin

Maligning Lowth, Or Bob...I'm sorry

2011-05-22T21:45:00.000-04:00

In rtfm* I had, in the grammar chapter, some harsh words for Bishop Robert Lowth. I accused him of applying the rules of Latin grammar to English and creating the rule that it's wrong to split an infinitive (i.e. "to boldly go").

However, I recently read “The Lexicographer’s Dilemma” by Jack Lynch (a great book, by the way). Mr. Lynch made a case for Bishop Lowth as a more reasonable man than I painted him. So I did what I should have done in the first place and did some research instead of counting on hearsay. In fact, Lowth didn't even discuss infinitives. He also said that it was wrong to apply the rules of another language to English (though, apparently, he wasn't good about following that rule).

In my defense (always a bad sign when you hear someone say that), I had my original information from a couple of good authorities: The Oxford Guide to English and Stephen Pinker’s “The Language Instinct” (both good books, though my favourite Pinker is his “Words and Rules” despite its unprepossessing topic). But, on this topic, they were...misleading.

Had I picked, as my example of Lowth inventing grammar rules, I should have used the ‘dangling participle’ rule (as in, “That’s where I’m going to.”). Then I would have been on firmer ground. However, seduced by the chance to make a Star Trek reference, I used the ‘split infinitive’ as my example. And I was wrong.

Fortunately, I'm planning a rewrite, anyway.

Reading or read

Instructions by Neil Gaiman and Charles Vess
Gotham Central Book 1: In the Line of Duty by Greg Rucka, Ed Brubaker and Michael
Lobster Johnson, Vol. 1: Iron Prometheus by Mike Mignola, Jason Armstrong and Dave Stewart
Safe As Houses by Eric Walters
The Divorced Kids Club and Other Stories by W.D. Valgardson
The Gift by Vladimir Nabokov
Lyra's Oxford by Philip Pullman
Once Upon a Time in the North by Philip Pullman
The Birth of the Clinic: An Archaeology of Medical Perception by Michel Foulcault
Odd and the Frost Giants by Neil Gaiman
The Umbrella Academy: Dallas by Gerard Way and Gabriel Ba
Fortunata and Jacinta: Two Stories of Married Women by Benito Perez Galdoz
Monster by Walter Dean Myers

Making Assumptions, Or Getting feedback until it hurts

2011-04-23T16:14:00.001-04:00

I recently posted a short tip on the Visual Studio Magazine website where I mentioned that I often comment out code because I never know when I might "want it back". This lead to a whole bunch of comments that I was foolish not to use source control. I suspect that it was the word "back" that caused readers to think that I was using comments as a substitute for keeping track of the changes to my code. In reality, I was doing something different (though, perhaps, equally reprehensible: using the version tracking system as a repository for code that, while not useful now, I might want later). What was interesting were the people who went from the initial assumption that I didn't use a key software tool to assumptions about what other nefarious practices I might engage in.

It occurs to me that this reflects the major problem that technical writers (or course designers) make: assumptions about the audience--the most common assumption being that the audience is just like the author. I recently recognized that I had fallen prey to this myself.

I was in New York last week teaching, for the first time, a Learning Tree course that I had rewritten last spring. I had included some technology in that course without any explanation to the audience: I simply assumed that, by the time the course ran, most people in the audience would be familiar with it. That turned out not to be the case. What's especially irritating about this is that I've been polling participants in other classes and knew that the technology wasn't well adopted yet.

So now I have two choices: Take the time to get participants up to speed in the technology or remove it from the course. Right now, I'm leaning towards removing it from the course. The technology isn't really core to the course's mandate and, quite frankly, the course is tight for time. However, there's a conference call coming up with the instructors for the course on Monday. The instructor pool for this course is excellent and they may well have a different perspective on the problem than I do.

By the way, while some of the commenters on that original tip only wanted to abuse me for my perceived short comings, several demonstrated what makes a great technical writer: they wanted to take the time to either correct my behaviour or, at the very least, to warn off other readers about the perils of doing what they thought I was doing.

Reading or read:

A Sentimental Journey and Other Writings by Laurence Sterne
The Hamlet by William Faulkner
The Day of the Locust by Nathanael West
Moon Over Manifest by Clare Vanderpool
Word After Word After Word by Patrica MacLachlan
Castle Rackrent by Maria Edgeworth
Portnoy's Complaint by Philip Roth
Airships by Barry Hannah
Three Novels: Soft Soap/The Leg/Will-o'-the-Wisp. by Willem. Elsschot
Chapel Road by Louis Paul Boon
Gustave Courbet by Sylvain Amic, Kathryn Calley Galitz, Laurence des Cars and Gustave Courbet

Getting it Wrong, Or Even Jove nods

2011-04-02T12:20:00.000-04:00

I'm in the process of revising the technical writing course that I created for Learning Tree International. A couple of revisions back, I introduced using the OODA loop as a tool for analyzing the reader's needs in a particular scenario. Reviewing that material, I've come to realize that I did just an awful job.

For someone who thinks its very important to tie information to what matters to the reader, I seemed to have deliberately gone out of my way to present the topic in as abstract a manner as possible: lots of graphics with floating circles and pastel colours. When I think of the instructors that had to put those slides up and then try to connect the material to the course participants' lives... Well, I feel badly.

Anyway, I've done a significant rewrite and am feeling much better about the material. I've revised the graphics and the text to tie into a typical task and then to follow up by tying into a previous example in the course. Hopefully, I won't come back in six months and realize that I've just botched the explanation in a new and more exciting way.

By the way: Does everyone else but me know that, on your car's gas guage, there's a little gas pump icon that indicates which side of the car the gas tank fills from? My wife and I discovered this yesterday: on her car this is a little arrow pointing to the left and, on my car, a little arrow pointing to the right.

The sad thing is that we've been driving our cars for six or seven years. And I won't talk about the number of rental cars where we've pulled up at the pump and realized that we didn't know where the gas cap was--and the necessary information was right in front of it.

A failure in the first O of the OODA loop.

Reading or read

Hay: Poems by Paul Muldoon

Support Your Local Author, or If you're not Canadian this column is pointless

2011-03-28T19:12:00.000-04:00

I like reading and listening to local artists. Right now, for instance, I've got music on by Lara St. John--she was born and raised about an hour and a half from here, in London.

When it comes to local reading matter, I'll admit that I'm spoiled. The great short-story writer Alice Munro is probably within a 45 minute drive from here. The novelist Joan Barfoot lives in London. About 90 minutes from here is Sarnia where Don Gutteridge writes novels and poetry. One of the finalists for the Canada Reads program last year was a novel set in Sarnia (Fruit). I also lived in Toronto for many years and visit/work there for two or three works every month: A couple of years ago, I read a great Toronto novel by Michael Redhill. I grew up on the prairies and am constantly finding new authors from out west (most recently: Sharon Butala).

I think there's a bunch of reasons local authors appeal to me. For one, I get a big kick of recognizing settings. I think I know the exact stripmall that appears in Fruit. A novel by David Berger talked about a stretch of road in Winnipeg that I regularly biked up and down when I was growing up. I think authors writing about what's around me also help me understand the world I live in (and, as a result, understand myself better). Reading also helps me understand the world I only get to visit: When I travel to other places I always try to read their local authors and pick up music or art by local artists (missed a bet when I was in Moncton a few months back).

Which leads to my complaint.

About two years ago, a very well received novel, At the Corner of Hope, written by a London author, came out. This year, one of the finalists for the Taylor award for creative non-fiction was The Geography of Arrival, also set in London. Can I buy either? Not really, no.

I live in a little town, Goderich, where I don't really have access to a bookstore. However, I do get to major urban centres all the time (primarily, Toronto). In the US, there are several major bookstore chains (Barnes & Noble, Borders, BooksAMillion) that have wiped out the independent bookstores. Up here, there's just one (Chapters) doing the same.

I admit it: I love Chapters. When I work in Toronto, it's just a question of how much of the money I make I will leave at a Chapters store. Some weeks, it's just a break-even proposition. Heck, some weeks, I would have made more money if I'd turned down the gig and stayed home.

But it means that if Chapters doesn't carry the book, I can't get it...and Chapters doesn't stock either of At the Corner of Hope or The Geography of Arrival--not even in the store they call The World's Biggest Bookstore.

That doesn't mean I couldn't get the books if I wanted to. The publishers of each of these books assure me, on their respective Websites, that if I pay shipping and handling, I can get my own copies of these books. I can even order the books from Chapters, online. But I can't do what I love to do: Walk into a store, pick up a warm book, buy it, take it home, and read it.

I'm not sure what the problem is that prevents Chapters from putting these books on its shelves. But, since Chapters has, effectively, turned itself into "Canada's Bookstore" by virtually eliminating the independent bookstore, I'm surprised it's not carrying Canada's books.

Reading or read

The Automatiste Revolution: Montreal 1941 - 1960 by Roald Nasgaard and Ray Ellenwood
Morrice: A great Canadian artist rediscovered. by G. Blair Laing
Group of Seven in Western Canada by Cathy Mastin
Doom Patrol, Vol. 6: Planet Love by Grant Morrison and Richard Case

Superlatives, Or Crminal language

2011-03-21T17:52:00.002-04:00

I'm a big fan of the show "Criminal Minds" which shows, in reruns,on the A&E channel. A&E's ad for the show describes the show's heroes as being "on the hunt for the most twisted minds." That line bothers me: That the criminal involved is "the most twisted."

In the show, one of the characters--J.J.--is responsible for accepting/rejecting requests for the team. So, presumably, she would be the person making the decision on who's got the "most twisted mind". I have this vision of J.J. on the phone with someone requesting the team to come and help them :

J.J.: I understand...but, you know, I don't think your murderer counts as the most twisted mind.
(voice)
J.J.: Yes, the pig is good. We don't get a lot of pigs. But, unfortunately, I've got another killer in Nebraska. They have a pig and a monkey. Do you have a monkey to go with your pig?
(voice)
J.J.: No? Well, then, I guess we're going to Nebraska...
(voice)
J.J.: Sorry, pardon?
(voice)
J.J.: Negligee? Your pig is in dressed in woman's underwear?
(voice)
J.J.: One second (changes lines on phone). Hello, Nebraska? Is either your pig or monkey wearing woman's underwear?
(other voice)
J.J.: That's too bad--so close! (hangs up, returns to first phone line) Congratulations, sir! You have the most twisted mind. We're rolling out the jet.

Now, I recognize that English is a rational/organic language rather than a logical language. I understand that a woman can feel she's "a little bit pregnant"; I get what Thomas Jefferson means when he says that he and his compatriots intent to form a "more perfect" union. But, it seems to me, that (unless you're Thomas Jefferson) you should honour the logic of good/better/best and some/more/most.

Reading or read

Wolf Hall: A Novel by Hillary Mantel (Audio)
The Known World by Edward P. Jones (Audio)
Doom Patrol, Book 4: Musclebound by Grant Morrison
Doom Patrol, Book 5: Magic Bus by Grant Morrison
2666: A Novel by Roberto Bolaño
Passionate Journey: A Vision in Woodcuts by Frans Masereel
The Invention Of The World by Jack Hodgins
Clarence Gagnon: An Introduction to His Life and Art by Anne Newlands

Forcing the reader, or Less, better?

2011-03-13T16:48:00.000-04:00

As I noted earlier, I'm taking another run at Hannah Arendt's book of political philosophy, "The Human Condition". I bought this book almost 40 years ago and periodically (like, every 10 or 15 years) try reading it. For whatever reason, this time I'm "getting it" and am about half-way through. I'll freely admit that this book is at the outside edge of "stuff I can understand" and I sympathize with people who have started the book and abandoned it.

Reading some of the more negative reviews of the book on Amazon.com, I notice a comment that I've seen on other "difficult" books: That the author's style is too verbose. It's a mystery to me how something complicated could be explained better with fewer words. And the reviewer's belief seems to be a common one: Many of the participants in my technical writing course list "writing more concisely" as one of their goals in taking the course.

But I think that this belief is part of a "cult of conciseness": Concision for its own sake/shorter is always better. Much of this cult can be traced back to "The Elements of Style" and the Plain Language movement. Both of these sources attacked unnecessary words. But, in both of these sources, "conciseness" was not an end in itself (or shouldn't have been)--concision was a means to an end: clearer writing.

Certainly, many writers add lots of unnecessary words--usually modifiers that add no value ("to be done weekly, every seven days,..") or stock phrases ("at this point in time" vs. "now"). And, yes, I also recognize readers are discouraged by long documents so a shorter document is more likely to be read. But the length of the document should be tailored to the readers' needs, not to any arbitrary standard of conciseness.

I do acknowledge that, when a reader is confused, more words won't necessarily help. I'll even acknowledge that my usual solution to confusion--more examples--may not help. But it's not the number of words that is the problem: It's the word choice that matters. The words have to be the right words for the reader and the examples have to be relevant to the reader and germane to the topic.

As an example: I did a technical talk once on Structured Query Language where, using the intialism (SQL) as an acronym, I kept referring to the topic as "sequel." This is an accepted pronunciation in the field, as is sounding out the initialism: ess-cue-ell (in writing, you can often tell which the author uses by looking at the articles: does the author write "an SQL statement" or "a SQL statement"). However, at least one person in the audience for this talk didn't know the "sequel" pronunciation and commented, after my talk, that it was fifteen minutes into my presentation before he knew what I was talking about. Whatever benefits my concision gained (using the single word--sequel--versus the longer, full term or the spelled out initialism) was lost on this participant. Now, when I talk about this topic, I switch between "Structured Query Language", ess-cue-ell, and sequel.

As technical writers our goal is to successfully explain things, to support the reader doing something or making a decision that they would not otherwise be able to do (or do as well) without our help. We should use as many words as required for the audience, their scenario, and our purposes...and then stop. Do the words add value? Leave them in; Otherwise, throw the bums out. And, if you go back to both "The Elements of Style" and the Plain Language movement, you'll find that's their story also.

Concision falls out of doing the right thing for your audience. It's not a separate, parallel process.

And if our reader doesn't need our help (or will never read our documents) then we shouldn't write at all. Now, that's concision.

Reading or read

JLA Deluxe Edition Vol. 4 by Grant Morrison
Doom Patrol, Book 1: Crawling From the Wreckage by Grant Morrison
Doom Patrol, Book 2: The Painting That Ate Paris by Grant Morrison
Doom Patrol, Book 3: Down Paradise Way by Grant Morrison
Orlando by Virginia Woolf
First Love by Ivan Turgenev
David Blackwood: Master Printmaker by William Gough
Goya by Enriqueta Harris
Abstract Painting in Canada by Roald Nasgaard
Cervantes: Exemplary Stories by Miguel de Cervantes Saavedra
On Thin Ice by Jamie Bastedo
Opened Ground: Selected Poems, 1966-1996 by Seanus Heaney

Looking at a New Course, Or It's not always about the content

2011-02-20T19:11:00.001-05:00

I'm looking at another Learning Tree course in the hopes that I can get the author's job for it. This course is slightly different from the previous one that I worked on as author. In that course, the content was excellent but it was the wrong content for the audience that was showing up to take the course. This course's content is also excellent and is probably exactly what the audience attending the course wants and needs. The content is also well presented.

Yet this course isn't getting the evaluations from the participants that Learning Tree expects. But the first thing to recognize is what the phrase "Learning Tree expects" means: Learning Tree is unhappy if less than 75% of the course participants think that the course is perfect. I'll pass over the sanity of that expectation and note that just over 50% of the participants taking this course think it's perfect. So Learning Tree is looking for way to improve the course: why doesn't this course achieve that level?

The answer is my usual one: audience.

People who write courses (and teach them) are good at taking new knowledge and applying it. In fact, given new knowledge, these people--now that they have a solution--often go around looking for a problem to apply it to. People who take courses, on the other hand, are less good at seeing how to apply what they see as abstract knowledge to their problems. Instead, what people-taking-courses have are problems. What they come to a class for are solutions to those problems. They want and expect a bright line to be drawn from the solutions presented in class to their problems. That's where this course isn't living up to the quality of its content.

For instance, while most of the people taking the course are in service industries, the course's case study focuses on a manufacturing company. This dichotomy, all by itself, makes it difficult for some course participants to apply the course's knowledge to their organization.
Another example: The course's objectives are laid out at the start of the course. The course's first objective is that participants will be able to "Define the term xxxx." Since most participants don't feel that defining terms is a critical problem for them, this objective has no value to them.
Most participants are looking for a reliable process: Important problems for them are "What do I do first?", "What do I do next?" The course does imply a process by the order that the content is presented in--but the process is never explicitly stated. As a result, many participants will feel that they have lots of knowledge but no idea when and how to apply it. In addition, I think that people often use a process to organize their knowledge. So, in the absence of a process, the course's content is going to seem confusing, unwieldy, and overwhelming.

But, thanks to this course, I think that I can calculate the percentage of people who need help in applying knowledge to their problems. Right now, somewhere between 50% and 60% of the people taking this course think it's perfect (it really is a very good course). That means that somewhere between 40% and 50% of the audience needs the kind of guidance that this course doesn't provide.

I guess I would sum up the issue like this: Many authors know "the answers". They're even good at expressing "the answers". What they aren't as good at are "the questions"--which is what matters to connect to the people taking the course.

Reading or read

The League of Extraordinary Gentlemen, Vol. 1 by Alan Moore and Kevin O'Neill
The League of Extraordinary Gentlemen, Vol. 2 by Alan Moore and Kevin O'Neill
The League of Extraordinary Gentlemen: The Black Dossier by Alan Moore and Kevin O'Neill
The League of Extraordinary Gentlemen: Century 1910 by Alan Moore and Kevin O'Neill
Cool Water by Dianne Warren
The Raga Guide: Survey of 74 Hindustani Ragas by Joep Bor

Public and Private, or What did happen to boom boxes?

2011-02-13T21:52:00.000-05:00

Given that I spend so much time in front of groups of people as an instructor or presenter (and that I talk a lot), many people are surprised to discover that I consider myself an introvert (and my Myers-Briggs personality profile backs me up on this). Part of this is probably genetically determined: a result of being an Asperger's kid and both lacking in social skills and interest in same. But, whatever the reason, when I'm home, I'm quite happy to never leave the house.

I've been taking another run at Hannah Arendt's "The Human Condition" and one of the points she wants to make is the distinction between the public sphere and the private sphere and how those two have intermixed over the centuries (basically from the city states of ancient Greece to the Western nations in the fifties).

One of the reasons that I've been thinking of this is that Sunday Morning (the CBS television show) had a segment today about boom boxes and how they are, now, a item of nostalgia. They've been replaced, first by the Walkman, then by the personal CD player, and now by MP3 players. It occurred to me that boom boxes were, essentially, a public activity. The point of the boxes was to make it possible for your music to be heard by yourself and others. MP3 players, on the other hand, are essentially private: while you can get speakers for them, most of listen on headsets. But the boom boxes could also have headphones, there was no reason why they had to come with speakers. So, in my own life, I've seen something move from being a necessarily public activity (portable-music-with-speakers) to private (portable-music-with-headphones).

One of the cases Ms. Arendt wants to make is that the Greeks felt that excellence could only be achieved in the public sphere: Glorious deeds done of one's own free will in the sight of others. Certainly, the idea of excellence could not be applied either to what one did to earn your pay (work) or what you did to stay alive (labour). We have a broader view of where one can achieve excellence.

It occurred to me that this probably has a lot to do with why technical writing is so important to me. First, it is an essentially public activity: your writing is useless without others reading it. It's also a contribution to the life of others--the purpose of technical writing is to help others do something or make a decision in a way that those others wouldn't have been able to do without the technical document.

But, even in a team environment, writing is essentially a private activity. When you are actually writing (unless the tenets of Extreme Programming reach into the field) you are working by yourself. So I get my privacy, get to make a contribution to others, and do so in a public way.

Reading or read

Green Henry by Gottfried Keller
Settlers by Vilhelm Moberg
The Human Condition by Hannah Arendt

Letting Go, or The reader's priorities

2011-02-06T23:06:00.000-05:00

I ran out of room in the library. Truth to tell, I ran out several months ago and have been piling books on the floor since then.

I had a backup plan: My youngest son was to have moved out by now and I could take over the bookshelves in his room (I've already occupied the shelves that already exist in the other kids' rooms). But he's still here.

I've had another option: two shelves of old electronics in the library that I could winnow down to, well, nothing (or close to it). That would give me space for four empty book shelves.

Since the beginning of my book reading mania, I've also bought more books than I could read and that "unread library" is also filling shelves. So I started a cull. Mostly what went were history books and non-fiction. About ten years ago, I realized that I read mostly non-fiction and that if I truly wanted to understand the world I lived in I needed to start inhabiting other people's minds. Initially, I guess that I figured that I would, eventually, go back to those books but--realistically--that's not going to happen: I have, as they say, moved on. So I cut about seven shelves of my "unread library" down to four and what was left in the shelf space that used to be occupied by the electronics. I also, by re-jigging a bookcase, opened space for a new shelf. I've probably got eight empty shelves * 2.5 feet = 20 feet. That should keep me for awhile.

Many books I could dispense with because I'm not the guy who bought that book any more. Others were on the shelf for sentimental reasons: to honour my parents/wife/children. I realized that I could be far more active about honouring them in speech and action than in keeping books I'll never read that are associated with them.

I'm also a list driven reader: I read because I'm working through some plan. So, for other books, the rule I used was: "By the time that I get through all the books between me and this book--will I have found other books that I will want to read before this book?" If the answer was yes, it meant that even when I got to that book, I wouldn't have gotten to that book.

Readers are like that, also. Readers will make value judgments about what we write and decide what they will read and when. If we write material that is of such low value to the reader that our readers will always have something more valuable to do--well, we're just wasting our time. And, by forcing the reader to sift the low value material from the high value material, wasting their time also.

But there's a second issue here. Let's say we write something that is of high value to our readers. How will our readers know? Since our readers will not be reading our work from cover to cover, we can't count on readers stumbling on our gems by accident. Rather than writing material that is important only to us we should free up that time to figure out ways for readers to find the material that's valuable to them.

So all of these books are off to a book sale where, hopefully, someone who will actually read them will find them. I'll miss them. But we're both better off.

Reading or read

Beautiful Losers by Leonard Cohen
Charles Sheeler: Paintings and Drawings by Carol Troyen
Gerhard Richter: Forty Years Of Painting by Robert Storr
The Moon of Letting Go: and Other Stories by Richard Van Camp

Training Words, Or I'd never thought of it that way...

2011-01-30T13:47:00.000-05:00

My wife and I were driving back from New York last week listening to a piece on either CBC or NPR on the relationships between humans and dogs. One of the experts mentioned how easy and natural it is to "tame puppies" and went on to say that it's so easy that we find it odd to say "tame puppies."

Thinking about it, he was right: We don't think of that initial period we spend with our companion animals as a matter of converting them from wild creatures to domestic, companion animals. It made me think about other word combinations that made me sit up and take notice. Switching from "fugitive slaves" to "escaping slaves" in talking of the American, pre-Civil War South removes the suggestion in "fugitive" that the slaves were running away from some justifiable imprisonment. When discussing Jews and Germans during the Holocaust, the switch from "killed" to "murdered", eliminates the suggestion that the regime had a right to put Jews to death.

It made me think of other combinations that apply to my work. I've tried to stop using the word "student" in favour of "participant," for instance, though I'm not sure my practice as an instructor reflects that terminology. What word would replace "teaching",or "explaining"? The issue is that the relationship between the subject and object is wrong "I teach participants" or "I explain to readers" has me doing something to others, when, in fact, all the work is done by the other party. "Facilitate," I suppose, but the word has been overused.

So what is it that readers/participants do? They "learn", I suppose, and "come to understand". So is what happens in technical writing (explaining) and in the classroom, "participants understand"? But that leaves out the teacher/writer altogether. It's a puzzlement.

Reading or read

George Sprott: (1894-1975) by Seth
Who Will Run the Frog Hospital by Lorrie Moore
God's Secretaries: The Making of the King James Bible by Adam Nicolson
October, Eight O'Clock Stories by Norman Manea
Maria Chapdelaine: A Tale of French Canada by Louis Hemon
As for Me and My House (New Canadian Library) by Sinclair Ross
The Black Spider by Jeremias Gotthelf

Show or Tell, or Don't just do something, stand there!

2011-01-17T08:53:00.000-05:00

I don't think that you have to tell people everything. First off, of course, you can only tell people anything if they're interested in it (or you can tie it to things that they're interested in). But, even then, "show" is often better than "tell". And, sometimes you don't need to do anything because people will figure it out for themselves: all you could do is muddy the waters.

For instance, in the SOA course one of the important distinctions that needs to be made is between a "service" and an "operation." The course has an activity where participants have to come up with a list of services. I was concerned that, in this activity, participants would include operations among their services. I wanted to forestall that.

My first thought, of course, was to provide a formal definition of "service" and "operation." The problem was that I couldn't come up with any set of words that I thought would actually be helpful to participants when they were trying to make the distinction. So I decided to finish up the definition by providing a set of examples. After reviewing those examples, I would present a set services and operations mixed in together and ask participants to mark which were services and which were operations.

This is all standard instructional design: provide the training, demonstrate the training, let participants exercise the training while providing coaching to fix any misunderstandings that are exposed.

But, quite frankly, I didn't think my "training" was providing any value. This activity occurs very early in the course when participants' understanding of "what a service is" is still pretty hazy. Piling on more definitions of more abstract terms was going to make things muddier rather than clearer.

So I considered just going straight to the second list of examples and asking participants to pick out the services. Participants had seen some examples of services at this point in the course and I thought the success rate would be pretty high. This time, the problem was in my examples: They were all pretty lame. And, quite frankly, understanding the examples to determine which were services and which were operations required some business knowledge. It seemed to me that if I took examples from a part of a business that participants weren't familiar with....well, they'd have a hard time figuring out what I was talking about, let alone deciding if I was talking about a service.

Then it occurred to me that the activity I was obsessing about required participants to list services: The participants would be generating their own examples. I could just circulate among the teams during the activity (there would only be three to five teams) and do some personal coaching to resolve any problems. I could leverage examples that meant something to the participants to make the distinction. This was brilliant!

Except that the problem never came up. In class, for whatever reason (perhaps because of the example services shown earlier in the course), the participants never seem to have the problem that I worried so much about. Asked to generate a list of services (and not operations) the teams almost invariably generated a list of services (and not operations).

So far, there's been exactly one team in exactly one class that inadvertently put an operation on their list. I jumped on that opportunity and just coached the hell out of it. I think the team thought I'd lost my mind.

(the subtitle for this post comes from a wonderful book by the choreographer Doris Humphrey: The Art of Making Dances. She has a list of rules in that book that, while they apply to making dances, also apply to many other things, including technical writing and instructional design)

Reading or read

Doghead: A Novel by Morten Ramshead
Unto a Good Land by Vilhelm Moberg
Wellington's Smallest Victory by Peter Hofshröer

Working on the SOA course

2011-01-09T08:21:00.002-05:00

I'm continuing to revise the Service Oriented Architecture course that I'm working on for Learning Tree International. It's funny (and I think that I've said this before): When I write a course I'm convinced that I've created the definitive treatment of the topic and established new standards in course design. When I teach the course for the first time with actual participants, I'm always (!!always!!) astonished to discover just how bad my course is.

For instance, when I went to teach my first version of this course, I discovered that participants were keenly interested in how to integrate this process with their standard project management process--a topic that I hadn't considered but, in retrospect, seems obvious. They also found many of the activities I built into the course either pointless or incomprehensible. I discovered that, even to me, several of the slides were incoherent and that there were many (actually: many, many) places throughout the course where I was adding lecture material that wasn't represented in the course notes.

This is the major benefit of actually teaching a course: You find out (primarily from the participants) just what a jerk you are.

So that led to a pretty significant rewrite of the course. That version (with a few tweaks to correct errors/typos) is what Learning Tree is running now. That course is showing promise--an instructor who was new to the course taught it for the first time and the feedback was good. I've had the opportunity to teach the version once myself and thought it went well (something I didn't feel about any of my teaches of my first version).

Now, there are a couple of caveats here. First: This course, historically, has been tremendously dependent on who was in the room--the mixture of the participants. So a couple of successful teaches doesn't tell us much about how the course will do with all of the people who want to take it. Secondly, when I say the course went well when I taught it, it really only went well for the first two days. I thought the third day sagged.

So I'm working on a revision to address my perception of the issues with the course's third day (and to tidy up the first two days).

One of the other benefits of having a course actually taught is that you get feedback from the instructors. One of the instructors for the course pointed out several issues with the course, for instance, most of which revolved around material now concentrated in the third day. That input formed a lot of my strategy for this revision.

But it's still too early to actually commit to revising the third day. Mostly what I'm going on at this point is my perception of what's wrong. And, let's face it, as the course author I'm going to colour everything pretty rosily. We won't really know what the real issues are with the course until more instructors teach it and we get more feedback from participants.

I remain cautiously optimistic. My initial feeling, when I was offered the opportunity to be the author on this course, was that the task was doomed. I was going to thoroughly enjoy writing the course and would appreciate the money I would get. However, I considered the course fundamentally "unwriteable" and, as a result, would eventually be replaced by another author. After all, just because a topic exists, it doesn't mean that it can be turned into a three day course in the Learning Tree format (e.g. imagine a course on "driving things": cars, boats, trucks, planes, horses, submarines. Just because you can come up with a title--"Driving: A Comprehensive Hands-On Introduction"--it doesn't mean that you can write a course for it). And I had some evidence for this belief: I'm the fourth author to tackle this course.

But some evolution in the field, some changes in the constraints on the course, and--most importantly--the ability to draw on the knowledge and experience of the previous authors and instructors gave me some help. Three months ago, I was convinced that there was no way to produce a version of this course that would make enough paying customers happy to make Learning Tree happy. Right now, I'm just not sure that it's impossible.Who knows? In a few more teaches, I might be convinced that it might be possible.

Reading or read:

The Anthologist: A Novel by Nicholson Baker
The Book of Good Love by Juan Ruiz
Robin Hood by James Clarke Holt
The Hunger Games by Suzanne Collins
The Book of Irish Verse: Irish Poetry From the Sixth Century to the Present by John Montague
Ancient Egypt (Travelers' Guide to the Ancient World)
Ancient Greece (Travelers' Guide to the Ancient World)
The Blue Fox by Sjon
Why We Make Mistakes: How We Look Without Seeing, Forget Things in Seconds, and Are All Pretty Sure We Are Way Above Average by Josepth T. Hallinan
Jar of Fools: A Picture Story by Jason Lutes

Back from Yellowknife, or Information no one needs

2010-12-12T12:28:00.000-05:00

Thanks to Learning Tree, Jan and I got to spend a week in Yellowknife (Jan also got to spend 5 minutes on Baffin Island changing planes and an hour in a plane in Rankin Inlet plus getting some personal attention when everything she was carrying set off the explosives sniffers on her way through the airport in Edmonton coming home).

It was wonderful. Met some terrific people, ate good food (arctic char, bison and musk-ox at Bullock's; Feugo's; Vietnamese Noodle Place, Chateau Nova). We went on a midnight dog sled ride with a curtain of white Northern Lights hanging off to the right, saw a local production of a great play, and listened to two brothers in a piano/clarinet duo (mostly classical but finishing with some klezmer tunes). Walked lots. Have to go back.

Looking at the sky at night, hearing the silence, and seeing those lights hanging there--I think people growing up in that kind of night would have a different relationship with God than I would.

And, of course, we came home with some books (there was a book signing at the local bookstore), some art/jewelery/clothes (local artists had a show on and there are lots of art galleries), and music.

But I have a new category of technical information: telling people stuff they don't need to know. What idiot, for instance, decided it would be a good idea to have a sign on main street that would tell me, every morning on my way to work, just exactly how far below zero it was?

But I also got back to a ton of work that I'd let hang, a client how needed me, and getting ready for Christmas (almost there).

Reading or Read

Kristin Lavransdatter (Vol. 1-3) by Sigrid Undset
The Death of the Adversary: A Novel by Hans Keilson
Nostalgia by Mircea Cartarescu
State of war: A novel - by Ninotchka Rosca
The Mouse Woman Trilogy by Christie Harris

Diction, Or Getting the words right...or saying them right

2010-11-22T18:06:00.001-05:00

When I was growing up in Regina, I had to say after school to take some sessions on pronouncing words carefully (I had a lisp). At one time these would have been called "elocution" lessons but, when I took them, they were called "diction" lessons. Historically, the word has meant "choosing words" (hence, Dictionary). When I'm teaching Learning Tree's Technical Writing course, I take a poll of the audience, asking what they think the meaning of the word "diction" is. I usually (not always) get a mixture of "pronouncing words correctly" and "choosing the right word."

As I said, the "choosing words" definition has been around longest--if you can get a dictionary printed about the start of the Twentieth century you'll find it listed as the first definition (and, often, the other definition doesn't appear at all). Over the course of the century, more dictionaries started listing "pronouncing words correctly" as the second definition. By the end of the century the "pronouncing" definition has often become the first listing and, in some English-as-a-Second-Language dictionaries, the only one.

This isn't, I think, a bad thing--the meaning of words does shift under our feet constantly ("silly" was originally a synonym for "saintly", for instance). But it does emphasize that we can't count on the dictionary to tell us what words mean. We need, after all, to know what the word means to our readers...and our readers may not have read the same dictionary that we did. Stamping our feet and holding our breath while insisting that words should retain whatever meaning they had when we were in public school is just a waste of perfectly good outrage.

So, we need to spend a lot of time listening to our readers. Either that, or avoid words, like "diction", whose meaning in the reader's mind we can't be sure of (technically, "diction" would be described as a 'wounded word'). The problem is that we won't know which words are wounded until it's too late. So listening is our best bet.

The problem there is that we don't listen very well: We tend to hear what we expect to hear. For instance, the further south in the US that I go the more likely it is that the response to "Thank you" will be "Unh-uh." It's amazing how many people don't seem to know that. In the Technical Writing class, I'll ask a class participant what, when they say "Thank you", people say to back them. Without hesitation, the participant will say "You're welcome." I'll then talk for awhile and, finally, return to the participant to say, "Thank you." A good proportion of the time the participant will respond with "No problem" or a wave of the hand or "Unh-uh."

It seems unlikely to me, if we're not even paying attention to what words we use, that we'll pay much attention to what other people mean by the words they actually do use. So, if we want to write successfully for our readers, we need to start by listening to our readers. Very, very carefully.

And, by the way, my mother thought that those lessons were the biggest waste of time in the world. I once pointed out that my lisp did, in fact, go away. She pointed out that my lisp went away the same time that my two front teeth grew back in.

Reading or read
The Fish Can Sing by Halldor Laxness
How to Live Safely in a Science Fictional Universe: A Novel by Charles Yu
Buffalo Woman by Dorothy M. Johnson

Travelling Part II

2010-11-14T14:19:00.001-05:00

After my rant a couple of weeks ago on dealing with irritating people when traveling, it seems like a good idea to talk about what you can do to make your time traveling better.

Be nice to the people you meet, especially the staff of the airports, hotels, taxis, and airlines. Ask for, don't demand, help. Respect their expertise (it's their job and they've probably been doing for at least as long as you've been doing yours). Tell them what you need and let them work out the best way to resolve your problem.
And remember what Jessica Rabbit (a real hottie) said about Roger Rabbit (something of a goof but, still, her husband): "He makes me laugh." These people are often doing the same thing over and over again with the only interruptions being unpleasent. If you can break that routine up with something that gives them a giggle...well, people will do almost anything for someone who will make them laugh.
Besides, laughter is the sound of someone's brain ticking over. And, especially if you're having a problem, it's good to have people thinking.

I'll be honest: I haven't always followed these guidelines myself. But when I don't, I'm always sorry; When I do, it always works out.

Reading or read

Antoni Tapies
The Passport by Herta Müller
Astro City: The Dark Age Book Two by Kurt Busiek, Brent Anderson, and Alex Ross

Punctuation, or You really have to see Victor Borge do it

2010-11-07T21:35:00.002-05:00

I like using punctuation marks. I try to use all of them. The thing is that there aren't many real punctuation marks--you can ignore the apostrophe as a punctuation mark for instance (I think of it as a kind of letter) which leaves fewer than ten to deal with. You could make your life more complicated with punctuation marks (the British poet, W. H. Auden said that he never understood punctuation) but you can also make some simplifying assumptions to eliminate most of your difficulties.

There are the three that go at the end of the sentence: period, exclamation mark, question mark. You should never use the exclamation mark (I tell authors whose articles I edit that they get one exclamation mark per article: use it wisely). If something isn't important to the reader, putting the band (!) at the end of the sentence won't make it important (nor will putting "Note that" at the front). If something is important tell the reader why it's important or tie it to something that's important to the reader. I only use the exclamation mark to indicate that I--the author--am surprised by something. So really, you only have to determine if your sentence is or isn't a question to determine if you end with a period (full stop in the UK) or a question mark.

Writers tend to have more trouble with the six punctuation marks that go inside sentences: the comma, the colon, the semi-colon, parentheses, quotation marks, and the em-dash (the dash that's about the width of the letter "m" in whatever font you're using).

Some are easy to handle. You can go your whole life without using the semi-colon, for instance. It's there when you want to jam two sentences together into one sentence. In that situation, of course, there's no reason why you can't just have two sentences separated by a period. But, if the two sentences are tightly related, you have the option of joining them with a semi-colon. Some style guides will have you capitalize the first letter after the semi-colon; some will not.

The quotation marks ("" or '') are easy to handle, assuming you need them at all because they always come in pairs and are used exclusively to enclose words taken literally from some other source. Parentheses have the same kind of regularity in that they are always used in pairs. You should use them to mark out material that could be left out of the sentence entirely (like this phrase).

Colons have at least two uses: To introduce a list and to signal a definition or explanation. The previous example used the colon to introduce a list. But the second purpose is more rare: It hardly happens at all anymore. So, again, you could use the colon exclusively for introducing a list and make your life considerably easier.

It's the comma that causes the most grief, I think. Part of the problem is that it, like the colon, has two separate uses: To separate items in a list and to mark out phrases in a sentence. When used to separate items in a list, you run into the issue of the serial or Oxford comma: do you have a comma before the "and" at the end of the list ("apples, bananas, and oranges") or do you omit it ("apples, bananas and oranges"). I'm a serial comma kind of guy myself but, really, it's a style guide issue: make a decision as to whether or not you use it and move on with your life.

Other than that, commas are used to mark out phrases. If the phrase appears at the start of the sentence then you need only one comma at the end of the phrase. I like to use that comma but, as the world moves to a more open punctuation style, it's becoming optional. Here again, if you want, you can omit that comma.

Commas are also used within sentences to mark out phrases, in which case (like parentheses) they always come in pairs: one at the start of the phrase and one at the end of the phrase. You can test to see if your commas are in the right place by removing everything between the commas. If you can't find the closing comma you should add it; if the sentence that's left makes no sense then you've put your commas in the wrong place and will need to move the beginning or ending comma. Like parentheses, the phrase inside the commas should be a "less important" part of the sentence.

You could make your punctuation more complicated but why? And if you do get frustrated, you can watch Victor Borge handle it better than anyone else.

Reading or read
The Cello Suites: J. S. Bach, Pablo Casals, and the Search for a Baroque Masterpiece by Eric Siblin
30,000 Years of Art: The Story of Human Creativity Across Time and Space by Editors of Phaidon
You Know Me Al by Ring Lardner

On Travelling,

2010-11-04T19:52:00.001-04:00

I've been neglecting the blog because (a) I've been swamped with work, and (b) on the road (I was Sleepless in Stockholm last week). This post reflects the last problem and isn't about technical writing at all.

Vogel's Advice for Travelers

If you can't lift your carry-on luggage over your head, it's not carry-on. Check it. When I get on the plane I have a single goal: To get to my seat. That someone in front of me is holding up the line because he/she/it can't get their enourmous suitcase up to the luggage bin drives me crazy. I appreciate that you don't want to be inconve nienced by having to wait for for checked baggage. That doesn't give you permission to inconvenience everyone else. And I won't discuss the hale and hearty looking man in Frankfurt who had so overloaded his carry-on bag that he couldn't even get it up onto the customs inspection table.
Dress for travel. I'm not talking about comfortable clothes: I'm talking about metal. Don't wear the belt with the metal buckle the size of your head (overcompensating for something?). Don't wear the metal spangly belt with the clasp, apparently, that you can't work (I'm talking to the woman ahead of me in line in Stockholm). If you're flying in the US, you will have to take off your shoes also: slip-ons are appropriate. Speaking of metal: You'll be standing in line to go through the X-ray for some time. Why not grasp the opportunity to remove some of the metal from your pockets (loose change, smartphone) and put it in that HONKING BIG SUITCASE YOU'RE DRAGGING.
Summing up the previous two items: Keep moving. We're all trying to get somewhere and, even in the nicest airports, we're still crowded. Since airlines are, apparently, trying to save money by having us walk most of the way to our destinations by putting the departure gates half-way out of town, we're probably in a hurry, too. Once in the planes we're really crowded. Don't stop. If you're confused, keep moving--the odds are good that, by moving on, you'll gather more information that will help you with your problem. If you need to stop, step to the side. DO NOT come to a complete halt directly in front of me. DO NOT, as the three young men at the end of the moving walkway in Toronto did, stop because one of you has dropped his jacket thereby blocking the person behind them with a suitcase so that she was trapped on the landing pad at the end of the walkway. Leaving, of course, no room, for all the rest of us being moved inexorably towards the end of the walkway.
Pay attention. I recognize that, as an English speaking person, I have an advantage: I speak everyone's second language. I do not expect you to know the language of whatever country you're in. I do expect you to pay attention to what's going on around you. Look ahead to the people in front of you. See what they're doing? Odds are good you'll have to do that also. And if you do speak English or the language of the country you're in: Listen to the instructions.
On an overseas flight, if you have bladder issues do NOT take the window seat. Take the aisle. I have the bladder of a sixteen year old and I take the aisle seat. Recognize your limitations.

One last thing: If you're sitting to the left of me when the meal comes remember that I wanted the aisle seat. I'm also left-handed. Get used to it.

Reading or read

Kristin Lavransdatter I: The Wreath by Sigrid Undset
The Unknown Soldier by Vaino Linna
The Brothers Lionheart by Astrid Lindgren
Seven Brothers by Aleksis Kivi
Hunger by Knut Hamsum
The Emigrants by Vilhelm Moberg
Troll: A Love Story by Johanna Sinisalo
Just My Type: A Book About Fonts by Simon Garfield

Processing Feedback, Or It's amazing what people want

2010-10-20T06:22:00.001-04:00

When writing technical documents or courses I've developed a real split personality...but, fortunately, it's the people I work with who are actually driven crazy.

When I finish a document or a course I'm convinced that this is the greatest document ever written/the best course in the world. This is especially true of writing courses where I'm convinced that the course is not only good but will revolutionize instructional design. So any people I'm working with get this impression of supreme confidence in my work.

But then I keep telling them: "This is a great start but we still have so much to do...." Of course, the immediate response is "What work! You said it was great! Why don't we do that work now!?!" The problem is that I don't know what needs to be done: We have to release the document or the course and start getting feedback from our audience. And I am always (!!always!!) surprised at that response.

For instance, I published a "Practical ASP.NET" column recently for Visual Studio Magazine that discussed several different ways for updating a Web page with new content on the fly. Practically the first comment to the article was one pointing out several additional topics that were essential to implementing the techniques but I hadn't addressed. I quickly put together a second column and Visual Studio Magazine posted it the following week. How did I miss those topics? Don't know--in retrospect it seems obvious. Presumably, a better audience analysis would have revealed that need but, if you had asked me, I would have said that I had done a pretty good audience analysis and I knew what my audience wanted. Yet, I was wrong.

The same is true of the latest course I've written for Learning Tree. When I was done with it (and incorporated the terrific feedback that I got from the course's technical editor, Mike Way begin_of_the_skype_highlighting end_of_the_skype_highlighting, about whom I can not say enough good things)--I thought it was the best course ever. I mean that.

But I also knew that, once I got it out in front of an audience, I'd learn a lot about it....and it wouldn't be good.

So Learning Tree sent me on a two week road trip to teach the course in New York and Chicago ("eating your own dog food") and I also ended up teaching the course a week after the trip ended in Ottawa. In the first teach (New York) I quickly discovered that there were a number of issues that the audience for this course was interested in that I was covering at all. I also discovered that some of the material that was included in the course had little or no value to the audience. Finally, some of the material required more...explication, let's say...than I had initially provided. Over the next two teaches, I layered in the additional material, made the case for the value of some of the material, reduced the emphasis on other material, and did a better job of explaining the rest. This has resulted in a new version of the course that I'll teach for the first time near the end of November.

And, once again, I think that this is the best course ever. And I'm equally sure that I'll learn a lot about it once I get into the classroom with it. I'm sure this second version of the course will be much (!!much!!) closer to what our audience wants/needs. But I bet that I'll have at least one more rewrite in it.

You know, I don't think that I actually "write" courses. I think I just "rewrite" courses. That initial version of the course is just there to give me something to work with.

Reading or read
Roots and Wings: Poetry From Spain 1900-1975 by Hardie St. Martin
One Hundred Famous Views of Edo by Hiroshige
La Regenta by Leopoldo Alas
Goya by Robert Hughes
In the Studio: Visits with Contemporary Cartoonists by Todd Hignite

Rehabiliting the Bishop, or My bad

2010-10-10T12:30:00.001-04:00

It appears that, in rtfm* that I've unfairly maligned Bishop Lowth. But, before my apology to his spirit, some background.

I recently finished the Lexicographer's Dilemma by Jack W. Lynch, a wonderful book about the difference between descriptive ("this is how the language works") and prescriptive ("this is how you should write and speak") grammarians. I've always fallen on the side descriptive side of this dispute: "the language as she is spoke." My advice to technical writers has always been to use the language and grammar of your audience. In rtfm* I used Bishop Lowth as an example of the kind of rules applied to the English language (not splitting infinitives, for instance, which is a perfectly normal thing for English speakers to do) and what technical writers shouldn't do.

Lexicographer's Dilemma made me realize two things. First, the value of prescriptive grammars and dictionaries: enourmous number of people want to speak and write like some social elite and, as a result, create a demand for those kinds of books. My value judgments on the "technical" accuracy of the rules promulgated by those books is irrelevant. Those books are actively and directly supporting the goals of their readers.

More importantly (to me, at any rate), the book corrected my impression of Bishop Lowth. It appears, from Mr. Lynch's book, that Lowth was no more prescriptive than his peers and less than many others--not at all the evil presence I described in rtfm*. It's my own fault: I relied on secondary sources rather than actually reading Lowth's work. That was reprehensible, to say the least, and I apologize to Bishop Lowth. It's the least I can do.*

*I.e. If I could do less, I would.

Reading or read
Scott Pilgrim, Vol. 1: Scott Pilgrim's Precious Little Life by Bryan Lee O'Malley
The Walnut Tree by Martha Blum

Providing Real Guidance, Or The most useless sign oin the world

2010-10-04T11:52:00.001-04:00

I'm just back from a 19 day road trip with my wife (Rockville, Maryland; New York, New York; Chicago, Illinois). We had a ball.
     In Rockville, we got back to the American Visionary Art Museum in Baltimore (wonderful place) and ate crabs on the waterfront.
We were in New York for 9 days so I finally saw Billy Elliott (Jan had seen it a couple of years back and kept saying I had to see it) and we also went to Lincoln Center (for the first time) to see a Persian musical group. I spent lots of money at the Stand bookstore and Barnes & Noble.
      We also got to see the group Pharoah's Daughter at a Klezmer brunch at a restaurant called City Winery. We'd seen the group once before in Toronto about two years ago and they are still wonderful--food was good, too.
    We hit two of our favourite restaurants (Daisy Mae's BBQ and Fatty Crab in their new location) but, being in an apartment, Jan was also able to cook some meals.
    We managed to explore some more of the Metropolitan museum: I hadn't seen their early 20th century stuff (Jan loves the Impressionists while I prefer Degas and Matisse). On a mezzanine floor they had some of the "modern masters" that I've never seen in the flesh: Chuck Close, George Segal, and Jackson Pollock (since I'd just finished reading a book about him, it was neat to stand in front of a couple of his pieces).

The 12 hour drive to Chicago was a bit of stretch for us but Jan had gotten us a great deal downtown at the Palmer House Inn for the one day we had in downtown Chicago. Amazing lobby, good rooms.
    Chicago turns out to be a great walking town. We walked to Xoco where we had extremely tasty sandwiches and unbelievable hot chocolate and churros.
    On our way to the Museum of Contemporary Art we passed a great new-and-second-hand bookstore right beside a CD store specializing in jazz/blues/20th century "serious" music. Well, actually, didn't pass.
        The Museum of Contemporary Art had a room full of Calder mobiles and stabiles that was..well..beautiful. Jan said it was "snowing Calders." There was another room of works by people riffing off of Calder which had some neat stuff also. The rest of the museum was mostly empty except for some works on paper. At least one artist, we agreed, would have benefited by being institutionalized...and kept away from little girls. And admission was free on Tuesday when we were there and there was a market in front of the man doors that, among other things, smelled wonderful.
     We also got to the Institute of Art which had unbelievable holdings of early 20th century artists. Lots of great American art, too: Winslow Homer, Whistler, and Sargent, for instance (a Sargent nude of a model with one of the great bums in art). The mid-20th century artists weren't as interesting (a couple of Demuth and a bunch of Georgia O'Keefes) but I ran across a guy who I'd never heard of before who I liked very much (Sheeler). That's one of the reasons you go to museums, after all. The late 20th century rooms had very cool stuff and I finally got to see some Gerhard Richter paintings "in the flesh."

None of which has anything to do with technical writing...except for a sign we saw on the way. Before we left Canada we were barreling down highway 6 and passed a sign that said:

       "Drive according to weather and traffic conditions"

How exactly do I do that? Drive faster? Drive slower? My personal complaint is that, in heavy weather, most drivers slow down too much rather than not enough. I suspect that the person who created this sign may not agree with me. I mean: If you're going to give me advice it's because you don't trust my judgment on the matter (or, if you do trust my judgment, why are you wasting my time?). Obviously those drivers I feel are driving too slowly think they are driving according to weather and traffic conditions and I do not. In fact, can you find anyone who, when asked, would say that they aren't driving according to weather and traffic conditions?
    This sign is the functional equivalent of, when you're standing on a ladder, someone calling up to you and saying "Don't Fall!" There's a good idea--but what do I do about it? Once I start toppling, I don't have much control over the whole "falling" process.
    The advice "Be Careful!" is marginally more useful. I have some idea of what "Be Careful" means and what I can do: take my time, pay attention to safety issues rather than just getting the job done, always have a grip on something, etc. I can do that! Doing those things will probably prevent starting the toppling part where I can't do anything. More specific advice, of course, would be more valuable here (e.g. "Here, put on this safety belt").
    Getting back to the stupid sign: Putting the sign up may have seemed like a "no harm, no foul" kind of decision: Even though the sign is useless, it does no harm. But, of course, it does.
     First, the sign cost money that can no longer be spent on something that is actually useful to the reader (costs: deciding on the text, deciding on doing it, deciding on where to put it, buying the raw materials, getting it built, sending people out to put it in). And, of course, I spent time looking at the sign (obviously). So, for that period of time, I wasn't driving according to traffic and weather conditions. It was just visual clutter that distracted me from what I should have been doing: driving according to weather and traffic conditions.

And the best part? Ten miles later, there was another one!

Reading or read

The Garden of Heaven: Poems of Hafiz by Hafix
Degas and The Dance by Jill DeVonyar and Richard Kendall
Gods' Man: A Novel in Woodcuts by Lynd Ward
Batman: Whatever Happened to the Caped Crusader? by Neil Gaiman
Secret Story by Ramsey Campbell
Unspeak: How Words Become Weapons, How Weapons Become a Message, and How That Message Becomes Reality by Steven Poole
Selected Poems by Carol Ann Duffy

Reassuring the reader, or Doing it right on the wrong side of town

2010-09-19T08:36:00.000-04:00

In an earlier post on writing commercial courses (Vogel's 12 Rules for Commercial Course Development) I listed that the three most important questions on the participant or reader's mind were "What do I do first?", "What do I do next?", and "What do I do NOW?". As I've been thinking about it, I think that the third question should really be "How do I know that I'm doing it right?"

When a reader is working in a new area--especially one where the reader has just picked up a lot of new knowledge--the reader is dealing with a lot of uncertainty. Not only is the reader unsure of whether or not they are doing the right thing (and what the correct next thing is), the reader is also concerned about what they just did. In a new field you find it difficult to assess success. Good technical writing provides support for letting the reader re-assure themselves that that they are, in fact, "getting it" and "getting it right."

The official term for this is feedback. However, that doesn't mean you should provide feedback at every step: Feedback, like anything else, is based on the reader's knowledge and expectations.

For instance, if your reader is a programmer and you're outlining some process that involves writing code, it's unnecessary to tell the reader that they must fix any syntax or compile time errors: Programmers know that syntax errors indicate an error. On the other hand, if the programmer is supposed to get an error (or even a warning) at some point in the process then you should advise the reader that that this particular warning or error doesn't represent a problem--precisely because of the reader's expectation that "no errors should occur."

While there is some flexibility in the feedback you provide during the process, it would be an unusual document that wouldn't provide the reader with information about what the final result is. Otherwise, how will the reader know if they got it right (assuming that the process doesn't end with a big flashing message that says "You've succeeded!")?

As always, if you're not sure what to include or what to leave out your first choice is to ask a few representatives of your typical reader. If your representatives are surprised at what they get when they are doing it right then you should include feedback to re-assure the reader; if your reader can easily determine whether they're succeeding or failing without your feedback then you should omit it.

Reading or read

The Lexicographer's Dilemma: by Jack Lynch
Intensity by Dean Koontz
The Klee Universe by Christine Hopfengart, Olivier Berggruen, Peter-Klaus Schuster, and Dieter Scholz
The Spirit: A Pop-up Graphic Novel by Will Eisner and Bruce Foster
Every Book Its Reader by Nicholas A. Basbanes

Structuring Documents, Or Making it obvious

2010-09-12T06:42:00.000-04:00

One of the complaints that people have about technical documents is that they don't "hang together"--that the material seems like a bunch of separate items. Often, that's the case: You may not need to worry about making it all hang together ("cohesion") if, for instance, you're writing a user manual for a software product. In that scenario you often end up discussing disparate features (topics) where (a) the topics don't have much to do with each other and (b) you don't expect the audience to read the topics together.

It's when you're working on more sophisticated explanations (whitepapers, for instance) where you expect the audience to read a substantial part of your document in the order that you present it that "making it all hang together" becomes important.

Your best strategy for achieving cohesion is, of course, to organize the material in a way that makes sense to your audience: To match the order that you use to cover the topics to the audience's world view. I often see documents that, as part of their introduction, describe the purpose of each section and why the sections appear in that order. If the audience is expected to read the material straight through (perhaps skipping the odd section that covers material the audience is already familiar with) this is useless material: The reader will never remember past page 10 what the purpose of section four is or why it belongs between sections three and five.

I often get the feeling that, in these introductions, the author is trying to convince the reader that this organization makes sense. The time would have been better spent determining how the audience would expect the material to be presented (perhaps by looking at the organization structure of well-regarded documents on similar topics that are read by the audience). In a book, given how few people read introductions, the time spent writing out these explanations is probably wasted, anyway. Rather than put the explanation for the organization in the introduction, the author would be better spent converting that explanation into into section headings where audience members can actually see it.

A well-structured set of headings tells the audience what each section is and demonstrates how the sections fit together--headings make the structure of your document visible. Headings are how audience members find their way through the document (skipping what they don't need to focus on what they do need).

So what are the rules:
1) A heading for a block of text should unambiguously tell the reader what's in the block of text
2) Where you have several topics (with their headings) grouped into a section, the heading for the section should describe what links the topics together.

Reverting to user manuals: In a car's user manual, for instance, you would expect to see this kind of structure:

Dealing with Problems with Your Car
     Engine Light On
     Weird Rumbling Noise from the Dashboard
     "Thwup-pa, Thwuap-pa" Sound From Outside the Car

And so on.

One last note: A heading is only useful to your reader if they can see it--if the heading stands out from the body text. A heading must be 33% larger than the text it accompanies for the human eye to see it as definitely larger (i.e. if your body text is 12 point, then your heading must be 16 point to be seen as larger). Section headings must be 33% larger than any subheadings to show that they are "more important" than their subheadings.

To stand out, headings must also be in a different font than your body text. If your body text is a serif font, put your headings in a san-serif font (and see Robin Williams Non-Designer's Design Book for more--and better!--advice on formatting).

Reading or read

A Criminal to Remember by Michael van Rooy
Yiddish Folktales by Beatrice Weinreich

Why pronouns are evil, Or Does Laura know?

2010-09-07T18:11:00.000-04:00

CNN Headline: Bush Aide Says He's Gay.

Parellelism, Or How will anyone know if you don't tell them

2010-09-07T10:32:00.000-04:00

I ran across another one of those articles that tells writers that it's important to construct sentences in parallel. That's good advice--the sentence "The new tasks are more complex, more tightly coupled, and set new priorities" takes longer for the reader to process than "The new tasks are more complex, more tightly coupled, and better prioritized." As similar phrases pile up, we appear to throw a switch in our brain as we prepare to process upcoming phrases. We tend to assume that the future will be much like the past and that the rest of the sentence will be like the part of the sentence we've already seen. If a later phrase violates that assumption then we have to unset the switch and move to a different processing method.

However, there's more that can be done to help the reader.

It's always good to remember that the reader only has access to the words on the page and not, for instance, to the author's intent. You can help the reader throw that switch by pointing out that you're about to begin a repeated structure. For instance, the sentence "Rights can be assigned directly to a user or through a group" has a parallel structure ("to a user" and "through a group"). But, while grammatically similar in structure, the parallelism is hard for the reader to spot.

The easiest way to signal to the reader that a parallel structure is about to begin is to repeat a key word. Repeating the keyword, in this example, "assigned" would tell the reader that you're going to repeat the structure "Rights can be assigned directly to a user or assigned through a group."

Reading or read

The Second Scroll by Abraham Moses Klein
Exit Lines by Joan Barfoot
Collected Poems (Norton Library) by Patrick Kavanagh

Establishing Context, or Putting first things first

2010-08-28T18:02:00.000-04:00

In a recent article that I wrote for Visual Studio Magazine (my first cover article for a journal that I didn't edit!) I made a claim that was immediately challenged by one of my on-line readers. I was right (of course) but so was the reader--it's just that I was right for the scenario that I was discussing and the reader was right for a different scenario.

In my technical writing course I always stress that the format for a section is "When, Information Critical to the Reader, Additional Stuff". That first part (the When) establishes when the information applies: It establishes the context for any subsequent information. In a side bar to my article I had made "claim A" and then later added "in scenario A." My reader pointed out that my statement was complete rubbish but was thinking about a different scenario (and, to be honest, the reader was considering the scenario that the main article focused on).

Had I followed by own advice and began the sidebar with "In scenario A, claim A is true" I could have avoided misleading my reader. This is the usual problem that technical writers have when dealing with material they're personally familiar with (I'm a programmer in another life). I call it the anthropic failure: "I know what I meant therefore my readers should also."

Oh, well and I'll try to do a better job next time.

You can read the article (and the exchange) here.

Reading or read:

The Authentic Gospel of Jesus by Geza Vermes
Selected Translations: Poems by Ted Hughes and Daniel Weissbort

Being Explicit, or I think we need to talk about this

2010-08-22T12:04:00.001-04:00

Another busy week--so busy that I didn't get a chance to post last week. In addition to teaching last week, Jan and I drove to Ottawa (wonderful week there: ate at the Sweetgrass Bistro with some new friends and Serena Williamson who gave us a copy of the CD she based her one woman show around, prowled around Byward Market and brought home some unpasteurized Quebec cheese, cool sausages, and duck fat). Learning Tree's marketing arm wanted some input from me about the SOA course I wrote for them (running for the first time in New York near the end of September and then--possibly--in Chicago). In there, I was also commissioning and editing articles for Learning Tree's Management Insight's newsletter and trying to get caught up with my responsibilities with Visual Studio Magazine (who are being incredibly patient). I did a little bit of software development in there, also, but it will be this week before I can really get to write code again. Oh, I almost forgot: I edited an early draft of my son's book on Transformers (there's more than meets the eye, there).

I also was doing some course development work for one of my clients and one of the first reviewers brought out a key point that I hadn't discussed. The material I was working on centred around creating a community in a social networking tool. The reviewer pointed out that users didn't have to enter all the information required to set up the community at one time: They could enter part of the information, save their work, and return at a later date to complete setting up the community. If a user was going to employ this tactic they'll want to leave the community's access level at "private" so no one can see the community until the user does complete it.

I came up with what I thought was a great way to cover this material. I went through the whole "community setup screen" covering all of the options during the "lecture" part of the course material. Then, in the "exercise" part of the course material, I walked the course participant only through the initial steps of setting up their community. After the first few steps, I suggested that the participants save their community and finish it later--pointing out that they should only make the community public when they finished setting it up. This would let the user see the tactic in action rather than just being told about it.

A later reviewer didn't notice my clever way of addressing this tactic and asked if we intended to cover it. We decided to insert a new bullet in the lecture portion of the course that explicitly called out the tactic. And, you know, I'm not sure that's a bad thing. I think that allowing the course participant to see, discover, and experience things is very valuable. But I also think that "saying things out loud" is important to, either before or after the experience. I know that I don't really remember anything until I see it in print (and I also recognize that may just be my personal kink).

Looking back, I can see that I'm moving more towards calling out material after giving the participant an opportunity to use it: Let the participant have the experience and then step in afterwords to help the participant make sense of what just happened. But the calling out part is still important I suspect that I might be omitting that.

And, by the way: My client's client (who we're building this course material for) has an amazing style guide. Fortunately, I'm not expected to memorize it because there's a dedicated reviewer who either brings my written material in line with the style guide or points out where I have to modify my text to be in line with the guide. The guide covers everything (for instance, using "because" instead of "since" unless referring to an ordered set of events). I suspect that I could start implementing some of the style guide when I write but I'm not sure that having the reviewer apply it isn't the most efficient use of everyone's time.

Reading or read

Letters to Juliet: Celebrating Shakespeare's Greatest Heroine, the Magical City of Verona, and the Power of Love by Lise Friedman and Ceil Friedman
The Janissary Tree: A Novel by Jason Goodwin
Jackson Pollock by Ellen G. Landau

No Help at All, or I don't know who do you think he's talking to?

2010-08-08T10:24:00.000-04:00

I'm doing some more instructional design for one of my favourite clients. My client is developing a training package for an internal SharePoint-like application used b a large technology company. The app lets users create networks of other users, write blogs, post their status, etc. It's exactly the kind of application that supports knowledge management and I wish that I'd been aware of it when I was working on Learning Tree's knowledge management course.

The application lets users customize their home page by adding/removing gizmos (and, optionally, configuring those gizmos). One of the objectives for the module that I'm writing is to enable users to "describe gizmos". Two things you should know:

We're supposed to draw our material for this course from an existing course
The audience for this course material is white-collar knowledge workers

The existing definition for these gizmos, which I was supposed to incorporate into the new course, was "Gizmos are prepackaged HTML that encapsulate software functionality." I can just imagine the audience for this course hearing that and nodding their heads, saying "Oh! Right! Whew--I'm glad that's taken care of."

I'm replacing that definition with a "Hole is to dig" kind of definition: "A gizmo is a tool you can use on your home page to see more information. You can add a gizmo to your page just by dragging it from the gallery of gizmos. To get to the gallery..."

Reading or read

The Wind from the East: A Novel by Almudena Grandes

Building a Visual Vocabulary, Or Drawing in readers

2010-08-01T14:11:00.000-04:00

I'm presently rewriting a course with a large number of graphics in it...which I'm replacing. I'm not sure that if it isn't just ego driving me because, quite frankly, the original graphics were good. The original graphics were very structural: generally speaking, a set of nested boxes with lines--which sounds dismissive and I don't mean to be. Boxes-with-lines are excellent tools when you're trying, for instance, to show people the structure of concepts (e.g. organizational charts, which show a very abstract concept: relationships). And that's what these graphics did and did very well. There was at least one box-with-lines graphic that I left in. In fact, I repeated it three or four times showing it in bits and pieces (and I simplified its first appearance).

So why am I replacing the existing graphic? I looked at what I was replacing them with: By and large I was putting in pictures of people, computers, scrolls--any physical analog that I could come up with. I realized that I was trying to do two things.

First, I was providing physical representations of material that I was concerned was going to be too abstract for our participants. This is a business course around software architecture to I wanted to suggest that the course material is very practical, very realistic. In addition, many of the course participants are business/management types rather than programmers: I wanted to link the topics we were talking about to things they would recognize from their world.

But I also realized that I wanted to create distinctive graphics that participants would remember and associate with concepts. The problem with box-and-line graphics is that all boxes and lines look alike (only colour and size provide any variation). I was replacing labeled boxes with (I hope) memorable images...and then repeating those images on many pages. I realized that I was building a vocabulary of images that participants would come to recognize. With a vocabulary built in early parts of the course, I could mix and match those images later in the course to explain new things (very much the way we mix and match known words to create new explanations).

This vocabulary, in addition to providing a parallel visual explanation to the word-driven explanations, also helps tie the course together. When I introduced a concept on one page, I would also introduce a corresponding image. When the concept cropped up on a later page, I also added the image. To (mis)quote T.S. Eliot, I was creating a "imagictive correlative" for the ideas in the course that I could use to reinforce the course's points and coherence.

I had another more nefarious point to using these images. At the end of each chapter there is a chapter summary that repeats the key points from the course. On that slide I also repeat the items from my graphic vocabulary that were introduced in that chapter (in miniature). At the end of the course I have an (graphic only and unreadable) slide that repeats all of the graphic vocabulary from the whole course (still in miniature). If nothing else, this slide--put it up just before the participants fill out their evals--sends the message that we've sure covered a heck of a lot of material.

That still leaves, of course, the question of whether or not the participants think it's valuable material.

Reading or read:

The Accordionist's Son: A Novel by Bernardo Atxaga
Tomorrow in the Battle Think On Me by Javier Marias
The Complete Poems, 1927-1979 by Elizabeth Bishop
Astrophel And Stella by Philip Sidney
Jonathan Strange & Mr Norrell by Susanna Clarke

Vogel's 12 Rules for Commercial Course Development, Or Trolling for evals

2010-07-18T14:23:00.003-04:00

People come to courses to get solutions for their problems—not to learn some technique, tool, or technology. The technique/tool/technology is just a means to an end. Which means: First you have to know the audience's problems. Then you have to know the field.
Set expectations appropriately: At the start of the course tell participants what problems you're going to solve. Encourage people who don't have those problems to leave. Now. Use this time to also get the participants to tell you what they care about.
Start in Chapter 2: Participants aren't interested in the history of the field, the underlying principles. Skip that. Start solving their problems right after setting expectations. If there are principles that will help them organize their problem solving skills or develop new skills keep it to one slide now and then. And consider describing those principles only after you've shown them how to solve their problems.
If you're not telling the participants how to do something or how to do it better…why are you taking up the participant's time? If you're not telling them how to do something that the participants care about you'd better either make them care (by tying it to something that the participants do care about) or drop it.
JITT/TIA: Just-in-Time Training—Don't tell the participants anything until just before they need it/Training in Action—as soon as you tell the participants something, give them a chance to do it. Right now.
Examples matter. Make sure that the examples reflect the participant's world with their problems. An immersive case study that where the participants have a role is best. A consistent case study throughout the course is more than "good enough." But if there's a problem that you're going to address that won't fit into a case study with the other problems, don't force it: make it a standalone exercise.
Respect your audience: They know a lot of stuff. At the very least they know what their problems are (though they may need help codifying that knowledge) and what their expectations are (as before).
Don't do trade-offs: something for this group, something for that group. Solve the problems that everyone in the audience shares.
The three biggest questions on the audience's mind are: "What do I do first?", "What do I do next?", and "What do I do NOW?" Give them roadmaps, decision trees, guides—tell them what to do when and when to do it.
Use graphics to explain. If you're an instructor or course author then you're probably word oriented. Most of the population is picture oriented—talk to them with graphics. Don't use visual puns: a word appears on the slide so you put a picture of it on the page ("software bus" = picture of a double-decker bus). Use flowcharts, diagrams, arrows, whatever to say in pictures what the slide says in words.
Throughout the course show progress. Advertise what you all have accomplished—otherwise participants may not notice.
Have a finish that delivers on the audience's goal. Then hand out the evaluation forms.

Reading or read

52 Ways of Looking at a Poem: A Poem for Every Week of the Year by Ruth Padel
Shortcomings by Adrian Tomine

Explaining Visually, Or No pun at all

2010-07-11T10:25:00.000-04:00

I write and teach courses for Learning Tree and, as a result, see a lot of courses written by other authors. I've just taken over a course that was handled by two other authors before it got to me (I suspect that the course is unwriteable, but I'll have fun trying to find a way to make it work for the participants turning up to take it). There were some very good graphics in the course but at least one complete dud which gives me a chance to talk about bad graphics.

The problem is that many (most?) writers when they think "graphics" think "picture" rather than "explaining things visually". So what happens, especially when creating a PowerPoint slide, is that the author picks some word on the page and adds a graphic that represents the word. It's not helpful--it's just a visual pun.

In this course, for instance, we talk about the enterprise service bus. So the original author (after one great graphic after another) dropped a picture of a double-decker British bus onto the slide. The next author kept the graphic, just dragging it to another place on the slide.

There's much that was wrong with this choice but the key point is that the graphic has no "explanatory value." In "Enterprise Service Bus", the metaphor being drawn on comes from an electrical bus (here, by the way, "bus" is short for "busbar"): A single item connecting multiple devices to which additional items can be plugged into; the picture implies that the metaphor is for a transport bus (here, by the way, "bus" is short for "autobus"): A large vehicle for transporting multiple people along a pre-determined route.

But this etymology is really pointless: The question is what the audience thinks/expects. My guess is that the audience doesn't make the connection between either kind of "bus." The real question is what the graphic can tell the audience. An "Enterprise Service Bus" is a software tool that supports plugging in (there's that electrical metaphor again) infinite number of software packages that can be used to process the inputs and outputs of the other plugged-in packages. Creating a graphic that builds off the electrical bus metaphor helps explain that, building off the transport bus (other than the concept of multiple passengers....somehow or other) does not.

So I took out the British bus graphic, put in a graphic of a long bar, and then added icons to the bar showing the typical kinds of packages that could be added to/accessed from an Enterprise Software bus. I needed that change: up until then, I really hadn't felt that I'd done much to improve the course that the previous two authors had passed on to me.

Just got back from our family's "no electronics" vacation where, as usual, I managed to get a lot of reading done. I violated the "no electronics" rule because I picked up this new course three days before I left and its due in four weeks. I'm so weak...

Reading or read

Luck: A Novel by Joan Barfoot
My Name Is Bosnia by Madeleine Gagnon
The Piano Tuner: A Novel by David Mason
The Jewish Messiah: A Novel by Arnon Grunberg
The Adventures of Johnny Vermillion by Loren D. Estleman
An Uncommon Enemy by Michelle Black
Solo Faces: A Novel by James Statler
Out Stealing Horses: A Novel by Per Petterson
Song of Kali by Dan Simmons

Amazon.com reviews, Or They let the loonies in for half price

2010-06-28T13:31:00.001-04:00

When you want to explain something you run into an essential dichotomy: what the writer wants and what the reader wants. The essence of great technical writing is crawling inside the reader's head to find what kind of explanation will work for the reader; poor technical writing occurs when writers concentrate on describing what they know and are interested in, using an explanation which works for the writer (while ineffective, this approach is considerably easier).

Amazon.com reviewers--especially those writing negative reviews--often reveal people who struggle with this dichotomy. The reviewer has just read some book that they just hated--so much so that the reviewer feels obliged to post a review on Amazon.com. The reviewer arrives at the book's page on the site and discovers any number of positive reviews--perhaps many of the reviews giving the book the full five stars. How can the reviewer reconcile the dichotomy between his or her opinion and that of all of these other readers?

Some reviewers have the courage of their convictions: They state their opinions. Really good reviewers describe what they want/look for in a book and go on to describe how this book failed to deliver on those requirements. I think these reviewers implicitly recognize that the other reviewers have valid opinions--that those other reviewers were looking for (and found) different things.These reviewers are also useful because these kind of reviews help readers who share the same requirements decide if they would enjoy the book.

I don't always agree with those requirements. For instance, I felt that a reviewer for Ruth Padel's "52 Ways of Looking at a Poem" on Amazon.co.uk wanted something from contemporary poetry that the reviewer wasn't going to get (a level of explicitness more common to prose than contemporary poetry, for instance). Since Ruth Padel's book is all about those things, the reviewer didn't enjoy the book. More importantly: A potential reader who had the same requirements as this reviewer could read the review and decide if they would enjoy the book.

Other reviewers lack that conviction in their opinion. It is inconceivable to these readers that their opinion of a work is not shared by all other readers: The only view of the world is theirs. So what is this reader to do about all the positive reviews? The response is almost always some combination of assuming (a) that the other readers were deluded/tricked and (b) that the other readers are lying (i.e. they didn't really like the book, they're just saying they did). This requires the reviewer to accuse the other readers of either being stupid or morally reprehensible, depending on the balance that the reviewer strikes between duplicity and lying.

My favourite example is a reviewer who gave "The Collected Fictions" of Jorge Luis Borges a two-star review. This reviewer comes down heavily on the "lying" side so much of the review is a diatribe against the moral reprehensibility of the reviewers who did like the book. I fully agree that not everyone is going to like Borges. While Borges certainly doesn't mind telling stories, he's at least as interested in playing games with story-telling. But developing characters, for instance, is not what Borges is interested in. I'm a big fan; my wife would hate him.

Because it's inconceivable to this reviewer that anyone could not share his opinion of Borges he's obliged to point out how unworthy those other reviewers are. He says that the book was recommended to him by "innumerable over-educated sycophants" (what does "over-educated" mean? That the other reviewer has more knowledge than the reviewer?). The word elitist appears in the review's title (interestingly enough, we still like the term "elite" when used with the military--we still say an 'elite fighting force' meaning a good thing--but it's now become a sneer when referring to anyone who might be smarter/more accomplished than the speaker). "Elite" also appears in the second sentence also as one of the descriptions of the people who do like Borges (the other word is "troglodytes"). He asserts that "no one reads Borges critically" which suggests that--while he reads Borges 'critically'--the other readers just swallow Borges 'uncritically.' Borges is only read by "the kind of people who never step foot out of Manhattan or Cambridge," who is a "pompous fellow," and "who think themselves intellectual elite."

Of course, the other benefit in describing what terrible people the other reviewers are, is that it lets you implicitly say what a wonderful person you are in comparison.

Reading or read:

Smilla's Sense of Snow by Peter Hoeg
Celestina (Drama Classics) by Fernando de Rojas (adapted by John Clifford)
The Aspern Papers by Henry James
Collected Poems by Philip Larkin and Anthony Thwaite
Luck: A Novel by Joan Barfoot

Thinking about a new Website, Or Apparently I don't have enough to do...

2010-06-20T13:26:00.001-04:00

My family loves interactive television. We are constantly hassling the figures on the screen (though they don't appear to listen to us). The most extreme examples are when my sons and I watch an old movie serial (or chapterplay). We begin by providing unasked for advice to the hero (who often needs it--"The Phantom" was an especially excellent example: Quite frankly, the man would have been lost without his dog, who was the brains behind the team).

But we move on to holding the hero and the rest of the cast up to derision. The best example here is the "The Phantom Creeps" staring Bela Lugosi as Dr. Alex Zarkov. Dr. Zarkov's name is now used within our family as the ultimate intensifier for the adjective "complicated" (as in "a plan of Zarkovian complexity"). Dr. Zarkov wouldn't create a disintegration ray--he would create a chemical that, when sprayed on a potential victim, would cause the victi to attract a tiny mechanical spider that, once it climbed onto the victim, would allow Dr. Zarkov to shoot the victim with a disintegration ray. If there was a hard way of doing things, Dr. Zarkov would find it. And you'll notice the term "potential victim". As you can imagine, with a process with this many steps things often went awry.

But we don't leave the production staff untouched, either. Dr. Zarkov's henchman (he has only one) is Monk who while escaping from the G-men who are tracking down Dr. Zarkov is show. In the back. Twice. Monk throws up his hands and collapses. The G-men rush over, bend down to touch Monk's neck and announce "He's OK. He's just stunned." It's hard to imagine what the writer was thinking of when he came up with that diagnosis.

Now you may think that this is going to turn into a diatribe against software developers who create user interfaces of Zarkovian complexity that I then have to explain. Not at all! Those developers are my bread and butter. What this does lead to is another form of interactive television: Making fun of commercials.

I know: it's easy pickings. But my recent blog on "butts" vs. "bums" in commercials made me aware of what a rich ground waits here to be tilled. I think there's an opportunity here for a new site called something like "What Commercials Tell Us." Commercials can have up to three different messages (which may conflict with each other) and over opportunity for a fourth.

Most commercials have an explicit message "Take this to feel better"--though that's optional: The original "Head On" commercial ("Applies Directly To Your Head!") didn't say that the product did anything: It merely provided instructions for how to use the product.

Then there is the implicit message ("People who use our product are smarter and better looking and have more friends than people who don't use our product"). There was one commercial I saw in the US (for insurance, I think) that had three scenes: A young white woman working in the kitchen of her own home; an older white man on the porch of his own home; a young black woman at her desk. There was a second version of the commercial that had the same format. The implicit messages seemed to be "White folk got homes; black folk got jobs."

The third messages is the inadvertent message. The "butts" vs. "bums" commercial sent a message about the kind of language that North Americans could tolerate, for instance.

Finally, there is often an opportunity for a new backstory. In the time available to them, commercials can't provide much detail. To compensate, they often provide "instantly recognizable" situations and count on the audience to provide a backstory consistent with the commercial's intent. The fun here is to provide a new backstory that is completely consistent with what happens "on screen" and completely at odds with the goals of the advertiser.

I may have some free time in July. If so, I'll set up the website. In the meantime, I can gather some material.

Reading or read

Stranger Music: Selected Poems and Songs by Leonard Cohen
The Complete Essex County by Jeff Lemire
The Nobody by Jeff Lemire
The Conqueror Worms by Brian Keene
Sunjata by Bamba Suso, Banna Kanute
The Island of Lost Maps: A True Story of Cartographic Crime by Miles Harvey
Abra : A Novel by Joan Barfoot
Boy's Life by Robert R. McCammon

New GPS, or So lifelike!

2010-06-13T08:37:00.001-04:00

We went on a road trip a couple of weeks ago (New York and Washington, D.C.) and, before we left, bought a new GPS. There is a point in here about technical writing but you'll have to persevere to get to it.

Our old GPS worked fine but the maps were out of date. On our road trip to Texas last January we found ourselves navigating through turnpikes that didn't appear on the map and taking off-ramps that didn't appear on the device (while driving past "phantom" ramps that were on the map but no longer existed on our plane of existence). We spent 15 or 20 miles driving along a road that didn't exist (the device showed empty field) while it constantly urged us to go to a much poorer road about 500 yards to our right.

We could have upgraded the maps, of course, but it would have cost $100 so considering buying a new device was also an option. A new device was attractive for a bunch of reasons: The old device was big and clunky so it could only be used in the car; newer devices, being slimmer, can be used when walking around. If we got a new device, we could also pass our old device onto some friends who needed to go to places they hadn't been to before. Looking at newer devices I realized that I could get a bigger screen (I now have a separate pair of reading glasses) and "lane guidance" (I was interested in seeing how that works).

And, besides, who doesn't like a new toy?

I also assumed that new devices would just be generally "better" (our existing device was about 6 years old). For instance, the old GPS had virtually no 'intertial navigation'--when it lost contact with the satellites, it lost its mind. We first noticed this when driving into New York at 10:00 at night: In the canyons formed by the building, the device lost satellite contact and alternated between spitting out random instructions and just giving up. We got into the habit of reviewing the lists of turns before we drove into an environment where we thought we would lose our signal.

Taking advantage of a sale we got a new device for about $170.00. The inertial navigation is much better: The new device guided us through the Holland tunnel, for instance, long after we went underground. The bigger screen contains more information while being easier to read (for instance, it tells me whether my next turn is a left or right turn much further in advance than the old device did). The lane guidance is useful but, sadly, only available for US locations. The reaction time isn't as good as the old device: For instance, when we missed a turn with the old device, it started figuring out a new route almost immediately; the new device takes about 5 seconds to recognize the problem. On the other hand, the new device takes into account more information than the old device did. The old device would give you the same route between two places every time you requested the route; the new device gives you different routes at different times of the day because it takes into account shifting traffic patterns: during rush hour, a route that's longer may take less time because travel times are shorter.

But what really impressed me was the improvement in the text to speech feature (which is why this discussion turns up in this blog). The new device does a much better job of communicating meaning rather than direction and it does that by being both more specific and more colloquial. For instance, when coming up an on-ramp to a highway, the new device doesn't use the generic "bear right" or "get into the right lane"; instead, it says what a person would say "Get onto the freeway" or "Merge onto the freeway". When you're approaching a T intersection where your road terminates, it doesn't say "Turn right" or "Turn left" (which are perfectly accurate)--it says what a person would say "When the road ends, turn left." One of the wonderful things about this last instruction is that it allows you to ignore any other turns between you and the T intersection: because the instruction is more specific, you know that the only intersection that matters is the one at the end of the road. Obviously, a lot more of the context ("the scenario") is being taken into account when generating text which results in better directions. They probably had a technical writer involved.

Addendum: The subtitle for this column, by the way, comes from an episode of Criminal Minds. One of the running gags on the show deals with the team's resident genius, Spencer Reid. In one particular episode, after commenting that the usual procedure in working out the result for a problem would have been to create a program, Spencer comments that he found it easier just to plug in his own values. One of the other team members reaches out, strokes his face, and comments "So lifelike." Part of the joke (for me) is that, rather than process all possible values for a problem, it is often easier to just plug in a couple of exploratory values, see what result you get, and then narrow your search to the most likely inputs. Often, in fact, you know enough about the problem to know that you don't need to look at "all possible values"--that the real world constraints mean that there are only a few values that are worth testing.

Reading or read

The T.E. Lawrence Poems by Gwendolyn MacEwen
The Hive: A Novel by Camilo Jose Cela
The Inquisitors' Manual by Antonio Lobo Antunes
Little Pilgrim: A Novel by Ko Un
Gripping Chapters: The Sound Movie Serial by Ron Backer

The Point of Technical Writing or Why it matters

2010-06-06T16:07:00.001-04:00

I'm putting together a potential package of communication courses for one of my clients. It would include basic writing skills then advance to business communication, technical writing (explaining things), and negotiation.

What I've come to realize is that the point of all communication--in business and, perhaps, in life--is to do two things: to explain (the point of technical writing) and to exchange value (negotiation).

If that's the case, these are the most important courses I'll ever work on. Which is sort of fun.

Reading or read

Sands of the Well by Denise Levertov
The House on the Borderland by William Hope Hodgson
Beyond the Pale and Other Stories by William Trevor
Andre Bieler: An artist's life and times by Frances K. Smith

Selecting Tutorial Topics, or The efficiency of not doing something is infinite

2010-06-02T11:27:00.002-04:00

I'm a member of the UPA (the Usability Professionals' Association), an association of people working in the field of user interface design. Exploiting the overlap between my technical writing side and my UI side, I'm working on an article for UX, the association's magazine on creating effective tutorials.

Some of the material that's going into this article I've covered elsewhere in this blog (look up the keywords associated with tutorials) but I realized that I'd never talked about the most important part: picking what to write tutorials about. I'm very concerned about the technical writer's efficiency, which is calculated by dividing the impact that the write has divided by the time spent. The highest efficiency is achieved when you do no work at all--when time spent is zero. After all, anything divided by 0 is infinitely large.

Remember that readers use tutorials when they have some goal they want to achieve. When users can't figure out what to do, they'll (sometimes) reach for a tutorial and work through the instructions, modifying the steps to meet their needs.

This means that there is no point in writing a tutorial that allows the user to "experience" some feature of the application or whose purpose is to demonstrate a piece of technology. Users will only take time out of their lives to work through a tutorial when they need the tutorial to meet one of their own goals. Your second step in creating a useful tutorial, then, is determine what your user's goals are—your first step is determining who the audience for the tutorial is. Only after you determine who the audience for your tutorial is can you determine what their goals are.

After determining your audiences and its goals, your third step is to determine the overlap between which of those goals will require your support and for which of those goals, the audience will seek out a tutorial. For tasks that the user regards as "intuitive", the user may choose the 'fumble around' strategy as the best way to achieve their goals rather than reach for a tutorial. Experts may choose to leverage existing knowledge (and would rather be caught dead then reading any help information). Where a user is surrounded by other users, users will find out how to perform common activities by asking surrounding users.

This process ensures that you only write tutorials that people will actually use. Or, from an efficiency point of view, that you spend zero time writing stuff that has no impact.

Reading or read

The Golden Age: Poems of the Spanish Renaissance by Edith Grossman
Rain: Poems by Don Paterson

Brits vs. North Amercians, or But we can't say that here

2010-05-31T18:55:00.002-04:00

While in Spain the people whose house we'd swapped with had a cable package that was all BBC, all the time. It was great: we got to see a bunch of Top Gear episodes we hadn't seen before.

There was a commercial that I loved: It featured charming young ladies in bikinis, short shorts, and tight skirts all shot from behind. It was, of course, a commercial for their running shoes.

As I watched it, it occurred to me that this commercial couldn't be shown in North America because it was too explicit. It wasn't the images that was the problem, however: it was the language. The voice-over kept emphasizing how wearing these running shoes would give you a great "bum".

Sure enough, when the commercial showed up on North American TV, the young ladies were now getting a great "butt". Still an 'earthy' word but not offensive in North America, apparently.

And don't get me started on trying to take "fanny" from North America to England".

Reading or read

Jonathan Strange & Mr Norrell: A Novel (Audio) by Susanna Clarke and Simon Prebble

Exercises count, or "Welcome home"

2010-05-31T18:49:00.001-04:00

I figured it out: since April 23rd and May 23rd, I slept in my own bed for seven nights--and all of those were in one continuous string between getting back from Spain (with a week in Toronto) and leaving on our "east coast road trip (New York to Alexandria, teaching the "Strategic Thinking for Operational Managers" course for the first time in the US for Learning Tree). Since I got back from Spain I've been trying to finish up the revision of my ASP.NET course and get back on deadline with Visual Studio Magazine.

Doing this revision of the course gave me a chance to look back at the way I've written exercises in the courses that I've written for Learning Tree. In the first course (way back in the late 90s) my goal in the exercises was to explain some technology...well, actually "to show off" some technology. Basically, the exercises proved that I hadn't lied in the lecture portion of the exercises. I bet that my courses were 75% lecture because, after all, if I said it then the participant's learned it, right? The exercises were also very "standalone": since all I was doing was demonstrating that I hadn't lied about the technology there was no need for the exercises to actually deliver a working application.

Learning Tree eventually gave me a book on Active Learning which emphasized that most people only really learned what they did, not what they were told. Learning Tree eventually advanced on this to say that it was silly to pack a course with knowledge that people only remembered 30% of it--you were better off to structure a course where people would remember 80% or 90% of the material even if you only covered 60% of the material (you do the math). About the same time, the company also started pushing us to have our exercises be built around a case study that reflected the real world: a "case study."

Here's my problem: In a technical course: I know the stuff in the course, the people taking the course didn't. What would "Active Learning" look like in this situation? I should talk, the participants should sit there listening and, eventually, they could do one of my exercises. The 'doing' part would be my exercises...which were, at best, 25% of the course time.

I eventually realized that what people did know was their problems and that was what was driving them into the course. One way I could incorporate activity into the course was to let participants talk about their problems and what they wanted to do. I could then base the course content around the problems of the people attending the course. I would drive the course forward by drawing a bright line between the participants' problems and the technology in the course.

If I wanted to do that, I also needed to provide more opportunities to do stuff in the course. The problem is that, with setting up to do a programming exercise and cleaning up afterwards, an exercise includes 5 minutes of unavoidable "overhead". I had the idea that, to make an exercise worthwhile, I needed an exercise to be "at least" 20 minutes in length. I was also still "lecture focused" so I felt that I needed to lecture through all the material that "hung together" before interrupting the lecture for an exercise (remember that 5 minutes of overhead?).

Putting those two things together resulted in 'death march' exercises that kept the participants banging away at their keyboards for 30 to 45 minutes at a stretch, often in exercises that did four or five different things because an exercise had to incorporate all of the topics covered in the previous lecture.

For the last couple of years, I've been moving in a different direction: JITT (Just-In-Time Training). My goal is a class where participants spend most (60% or better) of their time building the case study. The case study is interrupted by "just enough" training (lecture) to prepare the participants to do the next thing in the case study. Once we've covered enough material to do something in the case study, we implement that.

This sometimes means that the new version of the course may have one slide of lecture material followed by a slide with instructions on how to advance the case study. Sometimes the course has five or six slides that cover how to do the "next thing" and the participants do an exercise that takes 15 minutes (with overhead, I don't believe an exercise that requires more than a slide to describe will take less than 15 minutes). About once or twice a day, there may be an exercise that takes 20 minutes.

Each lecture portion takes somewhere between 3 and 15 minutes and leads immediately to extending the case study. Sometimes, following an exercise, the course covers material related to the stuff covered in the previous exercise that isn't part of the case study.

I like this new structure...but then, I would. It'll be interesting to see how (a) the paying customers and (b) the poor SOBs that have to teach the course feel.

Reading or read

This Earth of Mankind (Buru Quartet) by Pramoedya Ananta Toer
Twenty poems by Vicente Aleixandre
The Gospel According to Jesus Christ by Jose Saramgo
Blindness by Jose Saramago
Mythology and Folklore in South-East Asia by Jan Knappert and Graham Saunders
Dragon's Blood: The Pit Dragon Chronicles by Jane Yolen
The Shadow of Malabron: The Perilous Realm: Book One by Thomas Wharton
Three-Cornered Hat (Everyman's Library (Paper)) by Pedro Antonio De Alarcon
Lazarillo de Tormes and The Swindler: Two Spanish Picaresque Novels by Anonymous and Michael Alpert

Learning New Words, Or Right, that would be the same

2010-05-01T11:44:00.005-04:00

I got off the plane from Spain (there's a song there) and walked pretty much straight into a Learning Tree classroom to teach the .NET scalable applications course. Early in the morning of the first day, while I'm waiting for the class participants to show up, a woman walks in and says "Hi, I'm Elaine, Shawn's interpreter." I blinked benignly. "Shawn?", I ask politely.

It turns out that a guy named Shawn, who happens to be deaf, is attending the class and has two ASL interpreters coming along to translate. It takes two because--with the amount of talking that I do--the interpreters need to spell each other off. I could see it now: Elaine drops to the floor yelling to her partner "Aaaargh, my index finger! It's gone! Cover me!"

So Elaine and I worked out where she and the other interpreter (Rhonda) would sit, what seat would be optimal for them to work with Shawn, and so on. The class participants (including Shawn) showed up eventually, we all chatted, and started the class at 9:00.

By lunch, however. Learning Tree, being Learning Tree, had gone into overdrive to figure out the BEST possible arrangement to support the customer (at one point, the facilities staff were prepped to clear out half of the tables in the classroom in order to rearrange the whole room to optimize the sight lines for Shawn and the interpreters). In the end, we stuck with what Elaine and Rhonda had worked out in the morning. Shawn was a gent through all of this because (I imagine) these discussions are always awkward. He wants to be perceived as "Shawn," not as "the deaf guy," but he also needs to get his needs met or the four days are going to be a complete waste.

By noon on the first day, I had assumed that Sean was non-vocal and was only communicating with him through Elaine and Rhonda. But, on the third day of the course, when passing him in the hallway and waving "Hi" (as I usually do when I spot a participant in the hall--allows me to show that I recognize them without revealing that I don't know their actual name), Shawn spoke to me. Shawn grasped the opportunity to show me how to say "Good afternoon" in ASL and we both went on our way.

Now, when I teach in a non-English speaking country, I always have the participants teach me the "courtesy words" in their language. I got this from my brother who, when traveling in Europe, always learned how to say "Please", "Thank-you", "Excuse me", and "Which way to the public washrooms, quickly, please?" in the local language. So, on the morning of the fourth (and last) day of class, I asked Shawn to show me how to say "Good morning".

Shawn did and also gave me a quick history of the etymology of the phrases. It turns out that if you hold out one arm and move your hand over it (like the sun "going over the day" was the way Shawn put it.), you mean "afternoon". Moving your hand below your arm is, therefore, "morning." Over time, however, these have been shortened down so that the "morning" in "Good morning" is the just back of one hand against the palm of the other hand; similarly, the "morning" in "Good morning" is just the palm of one hand placed against your underarm. This is great because it hadn't occurred to me that, like other languages, ASL would change over time--it just reinforces my belief that people who want to keep a language "pure" are engaged in a hopeless quest.

By this time, I'm on a language roll. And, while I usually restrict myself to learning only one new word a day, I'd thrown away the first two days and I figured I could handle a third word in ASL in just two days without going into linguistic overload. So, at the end of the day, when Shawn is leaving, I grasp my opportunity. I ask Shawn, "So, what's the ASL for 'Goodbye' or 'Until next time'?".

Shawn looks at me a little oddly for a second. Then he lifts up his left hand, and waves "bye-bye". Right.

Of course.

<sigh>

Reading or read

The River at Green Knowe by L. M. Boston
Dark Back of Time by Javier Marias
Automatic World by Struan Sinclair

The Power of Leaving Stuff Out, or Home again, home again, riggety jig

2010-04-27T06:27:00.000-04:00

Jan and I made our way home again. The flight back had the best quality of all: it was uneventful. Well, actually, I'm not home yet, though Jan is. I landed in Toronto just in time to teach a programming course here for Learning Tree. So I'm in another (but familiar) hotel.

Coming back, we got to spend a day in Madrid wandering around the Passeo de Prado, eating on the boulevard, visiting museums, and picking up some last minute purchases. We got to the Raina Sofia museum where I got to stand in front of Guernica (there was lots of other neat modern art, too, most from artists we'd never heard of and a huge Calder mobile in a beautiful courtyard).

And, of course, I got into FNAC and bought some more CDs. I'm taking home about 18 CDs of music by Spanish musicians ranging from "early music" from European, Sephardic, and Moorish traditions from Jordi Savall and Eduardo Paniagua; to flamenco/nuevo flamenco artists like Enrique Morente, Paco de Lucia, Ojos de Brujo, Ketama; to pop artists like Fito and El Barrio; and some jazz from Chano Dominguez and Jorge Pardo. I've also discovered that I will probably never enjoy real flamenco singing in any but the smallest quantities. .

We discovered we were too footsore and tired from getting up at 5:00 and the stress of traveling to take as much advantage of Madrid as we could have. When we got to the Prado museum there was some sort of lineup system in place that allowed people to enter and leave in large groups and it all looked too complicated for us. Similarly, we hoped to take in a flamenco show in the evening but, instead, crawled into bed (well, I had a long bath first). I would have loved to have seen more Goyas, Velasquez, Murillos (we saw some in Vallencia). There was a Singer Sargent show that would have been wonderful. We will have to come back.

We got around in Madrid because of the fabulous Metro system. As a technical writer, it was great to see another variation of Harry Beck's map, originally developed for the London tube system. The London tube map is probably the most used technical drawing in the world (and a great book about is Mr. Beck's Underground Map: a history by Ken Garland) and should be an inspiration to technical writers everywhere.

What makes Beck's map interesting is that it works by stripping information out and leaving only what's necessary--and that's presented in a very stylized format that permits only horizontal, vertical, and 45 degree lines. The London map is not only useful, it is loved. When a recent version eliminated the stylized depiction of the Thames, public outcry forced it back in.

It was also good to see that the field keeps evolving. Most variations on Beck's map were failures. What has appeared more recently leaves the map alone and concentrates on helping the traveler with signage in the station. The new work draws on the field of wayfinding which supports how people navigate through space. In many transit systems, as you walk through the stations, you'll find maps that list all (and only) the stops on the route that you are approaching. This information is also presented in a very stylized order: no matter how twisty the route is, it's shown as a straight line; the station next on the route appears at the top and the station last on the route appears at the bottom. Again: less information, more help.

Reading or read

The Turbulent Term of Tyke Tiler by Gene Kemp
Love Visions by Geoffrey Chaucer
The Mouse and His Child by Russell Hoban
Corelli's Mandolin: A Novel by Louis De Bernieres
The Door by Margaret Atwood

Travel Arrangements, Or I can't see a volcano from here

2010-04-18T11:38:00.002-04:00

So now we can't leave Spain, which is an interesting experience. We were booked on a flight out tonight which would have got us to Toronto on Monday, in time for me to teach for Learning Tree on Wednesday. We gave that up because (a) it didn't seem likely to happen, and (b) the longer we waited the later it was going to be before we could get another flight.

So now, we're booked (I think) on a flight that leaves Sunday morning and gets us into Toronto on Sunday, in time to teach for Learning Tree on Tuesday. The reason for the "I think" is that we're not sure that Jan has a ticket for the first leg of the flight from Alicante to Madrid Saturday morning. Assuming she does (and SpanAir told me--I think--that she does) we get a day in Madrid: the Prado! Flamenco!

It was an interesting experience talking to Air Canada about rebooking. The first question I was asked was "Can you get to Rome" (all roads really do lead, apparently). It's an 18 hour drive (I smell !!road trip!!). We've also looked at taking a ferry across the Mediterranean to, for instance, Tunisia where for some astronomical sum of money, I can fly to New York.

So that's our current situation: To fly from where I'm not to somewhere I don't need to be for more money than I have. Of course, there are worse situations than to be stuck in someone's house in Spain...though we have run out of food. So it's off to the local restaurant tonight and the market tomorrow.

But this is the beauty of being a technical writer. I got eight columns done for Visual Studio Magazine (my "Practical ASP.NET column"), just about finished tech-editing a book for Pearson, arranged an interview for the ToolTracker blog (also with Visual Studio Magazine), and got some work done revising my ASP.NET course. And, even if I'd lost my Internet connection, I still would have been able to do about three quarters of those jobs.

Reading or read:

Guernica: The Biography of a Twentieth-Century Icon by Gijs van Hensbergen

The Power of People, or Stuck inside of Toledo with the immobile blues again (mama)

2010-04-16T04:14:00.001-04:00

Every once in awhile, it's good to be reminded that every piece of technical writing is actually a substitute for a real person. My wife and I are houseswapping in Spain and drove to Toledo last Sunday. At the exact moment that we pulled into the hotel garage in Toledo, billows of smoke poured out of the car and I lost power steering. I was able to wrestle* the car into a parking spot but that's where it stopped. On Monday, I started to look for a solution to my problem: to get the car fixed and get back to the house we were staying in Obra.

Technical writing helped: The note we had from the people we were houseswapping with pointed us to the document that told us how to get in touch with their roadside assistance service. The nice man from England that I spoke to had a tow truck to us within 15 minutes. After that, however, it was a question of how much English the people I had contact with could speak--there are real language skills!. So this column is a tribute to the mechanic who picked up the car but mostly to the amazing clerks at the Casona de la Reyna who took care of us (a great hotel, by the way, right at the edge of the Jewish quarter).

So, here's what I was reminded of: In the end, great technical writing, one way or another, connects us to other people. Either the material is a proxy for that other person or it's a conduit that allows us to make contact. Either way, technical writing is an opportunity for us to help each other.

And Toledo itself was amazing. And I mean that literally: I was amazed, constantly. I kept wandering around with this big grin on my face. The cathedral is a once in a life time experience: To stand under the Transparente is something you will never forget; the main chapel's altar is--like the Grand Canyon--more than the human eye and mind can actually absorb. And that leaves out the treasure (with its illuminated manuscripts and monstrance), the choir, and the art in the sanctuary (in one corner you are facing an El Greco, a Titian, a Raphael, and--my favourite--a Caravaggio). We were there four days instead of our planned 2.5 but, as a result, we got to see many things we would otherwise have missed. We also had great food: seafood (the Naviera--it turned out that the pulpy thing I was poking at was the fish's eye), great local lamb and pork (24 Alfilerito 24), and roast suckling pig (Del Cardenal). So, not a bad thing.

We did end up missing a concert we had booked in Valencia (Tokyo String Quartet--doing a lot of 20th century stuff so it had a real potential to drive Jan mad. But their first violinist is a Canadian, as was their previous first violinist). On the way home, we did stop in Valencia where we visited the FNAC and picked up a bunch of CDs by Spanish musicians (and "Sinatra and Basie at the Sands" for about $10.00CDN). We were also able to wander the museum of Belle Artes where we saw more wonderful things.

*not a metaphor: I wrestled a little in my youth at the YMCA and this recreated the experience excactly.

Reading or Read

All Souls by Javier Marias
Los Caprichos by Francisco Goya

Learning from Instructional Design, Or Stealing from the best

2010-04-05T04:54:00.003-04:00

While I'm here in Spain I'm grasping the opportunity to take some e-learning from Daryl L. Sink & Associates (they're the organization that Learning Tree partnered with to develop Learning Tree's Reality Plus courses). Since I do some instructional design for a couple of my clients, over the last 12 to 18 months I've been concentrating on increasing my knowledge in the field (my experience tends to take care of itself)--this training is part of that process.

The course that I'm taking from DSA is their "Course Development Workshop". I've been meaning to attend one of their "in-person" presentations of this course but work, so far, has always interfered. I finally decided that if I was going to do it at all, I'd best take advantage of their distance education, web-based version. I'm picking up lots of good stuff.

One of the tools that the course promotes is, I think, going to be especially useful to me and not only when I'm doing instructional design but also when I'm doing technical writing. In the course it's referred to as
M - A = D: Master - Actual = Difference

The tool consists of a three column table that lists:

The performance of a "Master" (not a "superstar" because it costs too much to train people to be superstars)
The performance you currently have (the "actual")
The difference

So, for technical writing, you might have this when comparing a new hire to a competent technical writier:

Master	Actual	Difference
Adjusts content and format for different audiences	Writes what he or she would want to read	Does not understand the demands of different audiences

It's actually a four column tool because DSA uses this in conjunction with a second table that lists the cause for each difference (e.g. knowledge, attitude, lack of essential tool).

In applying this to technical writing, a tweaked version of this table could be very useful in defining the knowledge domain for a document--one of the critical issues in designing a document. This table could go a long way to addressing the knowledge domain question: "What needs to be addressed in a particular document for a particular audience?" You only need, after all, to address the differences.

Of course, defining the knowledge domain is just the first step. Once you have defined the difference, the next step is determining how to address it--what content should be included to help the audience move from their current state to the required state?

It seems to me a small step to modify DSA's table to address the difference in knowledge/information between the required level of knowledge in the domain vs. the level of knowledge in document's audience. And it's an equally small step to extend the tool to include a tactic for addressing that difference. If I was writing a textbook on technical writing, I might create this version of the DSA table as part of designing the textbook's content:

Required	Actual	Tactic
Specify the different requirements of various audiences for the same knowledge domain	Treats all audiences as having the same needs as he or she does	Provide examples of different audience demands for the same knowledge domain. Contrast with what the author finds valuable

I'm finding this tool useful (I tried it out as part of revising a course proposal I put together for one of my clients) but obviously it needs work. Just because there is a difference and you have a way of addressing it, you don't necessarily have to address that difference. A prioritization step is also needed (DSA divides potential content up into three categories: Could, Should, and Must). It also seems to me that you need both tables: one to help you accurately define the difference and one to help you define a way of addressing it. Perhaps a five column version would work best: Master, Actual, Difference, Cause, Tactic? Too unwieldy?

And another critical point: DSA's original (M - A = D) spells out a word. My version (R - A = T) spells out an unfortunate word. And, as we all know, the success of any tool is dependent on its acronym.

Reading or read

Stars in My Pocket Like Grains of Sand by Samuel R. Delany
Soldiers of Salamis: A Novel by Javier Cercas

Looking for Books, or When in Spain do like the Brits

2010-03-30T01:46:00.004-04:00

Arrived in Spain Sunday night and spent yesterday (Monday) running around with Jan (and the other two members of our party) getting groceries and lost (not necessarily in that order).

I look on our visits to foreign countries as an excuse to read authors (and get music) from that country. So I look for bookstores and ransack them for local authors. I do recognize looking for English books in a foreign country is sort of dumb to begin with: People in Spain read in Spanish so the books I find here are going to be in Spanish.

The search isn't completely stupid, however. To support the tourist/ex-pat brigade the bookstores (especially at the airport) typically do stock a large number of books in English...but all by English authors (with the odd 'international success' translated from the original language). And, in town, the bookstores often have a shelf of books of "local authors in English." This was true in the two or three bookstores I went into in Stockholm, for instance, and the bookstore in Arnhem in the Netherlands that I visit when we're there. I draw no conclusions from this shelf often being flat on the ground--I'm still limber enough to get down and look.

Anyway, here in Spain we're staying in a small town called Orba (about an hour from Alicante and an hour and a half from Valencia)--no bookstores here. Everyone else arrived last Wednesday and had already been to the local markets so, today, at least in part to satisfy my hunger for bookstores, we went to a mall. I did find a bookstore but it was aimed exclusively at the ex-pat market. Lots of books in English but exactly six books by Spanish authors:

Three "world classics"

Don Quixote by Cervantes (Penguin)
The Exemplary Tales by Cervantes (Penguin)
The Conquest of New Spain by Diaz (Penguin)

A Dan Brown kind of thriller set in Italy and the US
Two "literary" novels

Soldiers of Salamis--A novel set in the Spanish Civil war
All Souls--a novel by a contemporary Spanish author (Javier Marias)...set in Oxford and based on the two years he spent teaching in Oxford.

I had actually found more variety in "Spanish authors in English" at the used bookstore I go to in Toronto. I had found "Soldiers of Salamis" there, a novel by Galdos (who, I gather, is considered the greatest Spanish author after Cervantes), several different versions of "Don Quixote", Zafon's 'international bestseller' "The Shadow of the Wind", a book of poetry by Lorca, and a book by a Galician author I hadn't heard of before that was delightful. And two of those books I stumbled across by accident because the authors had 'obviously Spanish' names that were close to the names of Spanish authors that I was looking for (and not finding)--which means there were probably more books by Spanish authors and I just didn't find them.

Meanwhile, the supermarket we went to had oodles and oodles of books by Spanish authors...all in Spanish. It's like some cruel joke. We're off to Valencia tomorrow for our first visit so, perhaps, I'll do better there.

What's that got to do with technical writing? It got me thinking: How often do we read the books that our audience reads? How well do we immerse ourselves in the language and culture of our audience? When we write for a very different audience, do we come across as "tourists"--not knowing the language or almost getting the words right but always just missing?

Reading or Read

The Umbrella Academy Volume 1 (v. 1) by Gerard Way and Gabriel Ba
Esther's Inheritance by Sandor Marai
The Girl Next Door by Jack Ketchum
Merlin and Company by Alvaro Cunqueiro
The Children of Green Knowe by L. M. Boston
Marianne Dreams by Catherine Storr
Conjure Wife by Friz Leiber
Poet in New York by Federico Garcia Lorca
The Midnight Fox by Betsy Byars
Don Quixote by Miquel De Cervantes Saavedra
The Land of Green Ginger by Noel Langley

Slammed with Work, Or The sun was in my eyes

2010-03-22T18:26:00.002-04:00

I've been ignoring this blog (which is too bad because it's one my gifts to myself) because I've been slammed with work. I'm now "Products Editor" at Visual Studio Magazine which means that I'm doing two reviews a month and maintaining a blog on .NET/Visual Studio tools there. Getting that ramped up required more effort than I had realized. I also did a couple of interviews in there that either made their way into my Practical ASP.NET column or will make their way into the products blog

I was also putting together a proposal to Learning Tree to author a course on User Interface Design (a subject near and dear to my heart). I tend to over compensate for my deficiencies as a course author by doing BIIIIIIIG proposals (this one ran to 20 pages: feel sorry for the poor product manager who feels morally obligated to read it).

And I taught my technical writing course for Learning Tree last week. I think it went well. I certainly had fun.

Mixed in there I'm reviewing the galley proofs for my Code Generation book (one more chapter to go!) and acting as technical editor on a Microsoft Access book. And, I was working with various authors to put together five articles for the Learning Tree newsletter (I dropped the ball on that one: I contacted Learning Tree about starting that process about a month ago, didn't follow up, and then they got back to me to get the process started a month later than I would have chosen). I also edited two history papers for my son (I learn lots).

And, of course, the ongoing marketing and client support efforts that are part of being an independent consultant.

My mother-in-law has been staying with us (that's a good thing) so we also celebrated her birthday on Sunday with lots and lots of people dropping around (well, lots for me: 25 or 26 people). Jan, of course, did all the work but I had to pay attention--always a strain. And, of course, we're getting ready to go to Spain for three works (though, again, Jan does all of that and I just tag along looking beautiful).

So that's my excuse.

Reading or read

Planetary Vol. 4: Spacetime Archaeology by Warren Ellis and John Casssaday
The Iron Man by Ted Hughes
The Iron Woman: A Sequel to the Iron Man by Ted Hughes
The Uses and Abuses of History by Margaret MacMillan

Effective Slides in Presentations, or Why PowerPoint doesn't suck

2010-03-06T15:49:00.002-05:00

It's become fashionable to diss PowerPoint. The article that I referenced in my last blog said this, for intance:

"Over-reliance on PowerPoint slides has brought more presentations to its knees than a ring full of World Wide Federation wrestlers. Unless you are trying to illustrate a very complex technical idea, PowerPoint slides are a distraction...You don't need PowerPoint to tell a story well." (hyphen added)

I'd be the first to admit that bad PowerPoint slides have damaged many presentations. However, so have not being prepared, talking about things that don't matter to the audience, speaking into the podium rather than with the audience, and many other things. I'd be willing to admit that bad PowerPoint can damage a good presentation but it certainly can't do nearly as much damage as, for instance, not speaking loud enough.

About the worst that can be said about PowerPoint is that too much time spent preparing your slides instead of preparing your presentation could kill a presentation--but that's not quite the same thing as saying that 'bad PowerPoint' kills a presentation". It's the difference between saying that "Money is the root of all evil" and "The love of money is the root of all evil" (and, by the way, the Bible says the second one, not the first).

You'll notice that the article I quoted talks about "over reliance on PowerPoint" which is a nice change from the usual knocks on PowerPoint. However, that author then goes on to say that PowerPoint slides are "a distraction" and that "you don't need PowerPoint."

Yes, you do.

I'm preparing a proposal for a client that includes a "creating effective PowerPoint" module so I've been codifying what would constitute 'effective PowerPoint'. I've decided that, as a minimum, you need PowerPoint for three things:

As your speaking notes. The surest way to ensure that you don't commit the real sins of speaking into the podium or reading what you've written is to not write your presentation down. Instead, use PowerPoint as your speaker notes--let your slides can prompt you as to what to say next. At the very least, you and your audience will be glancing at the same thing.
To expose your presentation's structure to your audience. Bring up a slide at the start of the presentation that lists tells your audience what you will be talking about; repeat that slide each time you change topics. The result: your audience will know where you are, where you're going, and be able to estimate how long it will take to get there.
As a visual aid. PowerPoint lets you do most of the things that you can't do with just words: Present graphics, show processes through animation, and so.

If those are the three things that your PowerPoint slides can do for you then these are the rules for creating PowerPoint slides that will meet those goals:

Build a set of structure slides. The first structure slide is your title slide--the first thing that your audience sees. Tell the audience what you're talking about. The second slide should either tell the audience what benefit they will get from your presentation or provide an opportunity for you to ask your audience to tell you what they want. The next slide lists your topics in the order they will appear. Subsequent structure slides repeat that list, highlighting the topic you're about to talk about.
Insert your speaker notes in between your structure slides. Create a set of slides consisting of keywords or phrases that will remind you of what you want to say. At its simplest, this means you'll have slides with between one and four bullet points with each bullet point one to six words in length. You can get these slides to do double duty: Since your audience will also be seeing these slides, include key words or concepts that you want your audience to remember on these slides.
Review your speaker notes and look for opportunities to replace your words with graphics. Is there something that would help readers "see" what you mean? A graphic, a chart, a picture, an animation, a video? All of these can be embedded in a PowerPoint slide. A good graphic can often do double duty: it's not only something to show to your audience, it can also act as your speaker notes to remind you of what you wanted to say.

The result is a presentation that will guide you through what you want to do without providing enough words to lure you into reading text to your audience. Do this, along with the stuff that I covered in my last blog, and you'll give a heck of a presentation

Reading or read

Doña Perfecta by Benito Perez Galdos

The Real 7 Rules for Making Great Technical Presentations, or Everyone else is stupid but me and thee (and I have some doubts about thee)

2010-02-27T17:54:00.003-05:00

The DevX.Com site recently posted an article called "7 Rules for Great Technical Presentations" by Bob Reselman (I know: but he's probably never heard of you, either). The article isn't without its merits (though it includes the usual cliche about how PowerPoint ruins presentations--a topic that I'll return to in a later blog). But most of the steps are wrong-headed and the article doesn't offer much in the way of advice that you could actually implement: lots of hand waving and modifiers but not much real practical advice.

The seven rules are:

Know thy stuff
It's a show; you're an actor; get used to it
Understand that it is really, really hard to look ridiculous
Forget PowerPoint; tell a story
Play Charades a lot
Example, examples, examples
It takes three shots to get it right

You know that you're in trouble when the first rule is "Know thy stuff" rather than "Know thy audience." The result of making "Know thy stuff" the first rule is that the poor defenseless audience is going to get inundated with a lot of technical information they are not interested in, that they will not be able to use, and that will make no difference in their lives. But then I'm worried about any list of rules that assumes that someone giving a technical presentation won't know their stuff--that's the part that I would have taken for granted.

The rest of the list seems to focus (with the exception of rule 6: "Example, examples, examples") on handling stage fright and giving a good performance. The author advises presenters to "entertain" and "engage" the audience but doesn't provide much in the way of practical advice on how you would achieve those goals (tell jokes? wear a funny nose?). He suggests that you find "the good story" in your presentation but provides no direction on how to find that story and--modifier alert!--what would qualify as a "good" story.

He then makes the biggest mistake of all by advising presenters to find the story that matters to the presenter--that this is the secret to stirring the imagination of your audience. After seeing many, many (many!) presentations where people talked about what mattered to them, I can assure you that this is not the way to stir anyone but yourself. Great presenters find out what matters to the audience and use that to stir their audience members.

The advice on playing charades, while it suggests that the author recognizes that presentations have a visual component, is particularly devoid of practical advice (except that you shouldn't use PowerPoint to provide that visual component, apparently).

The last two rules (about using examples and rehearsing) are so valuable, though, that they almost compensate for the windage in the rest of the set of rules. No advice on how to pick examples, though.

So what would a real set of seven useful rules look like? This is my list:

Know your audience: Figure out what they value, what matters to them. Talk about that. If you want to talk about something else make sure that you draw a bright line between what the audience values and what you want to talk about.
Know your audience's vocabulary: Find out the terms that make sense to your audience and use them. If you're presenting to social workers refer to the "impact on the community"; if you're talking to business people refer to the "contribution to the bottom line." Don't make them learn your vocabulary; tie what you want to talk about to the words they already use.
Use PowerPoint as your speaker notes. Your slides should have just enough text to remind you what to say next. That way you won't be reading your notes (or the screen). Your audience won't be reading the screen, either, because there's not much there.
Use PowerPoint to provide the visual component of your presentation. People watch presentations. Use PowerPoint to show pictures of what you're talking about, graphs, diagrams, flowcharts, etc. If you think that you can provide some additional visual interest with body movement, knock yourself out. I know that I can't stand still on stage but that has much to do with nervousness as anything else.
Figure out what your major topics are and put them in an order that means something to your audience. But--more importantly--right at the start bring up the topic list, explain what the order is and why the topics matter to the audience. At every topic change, show the topic list again and explain what the next topic is. If nothing else, your audience will be able to estimate how long it will be until you'll stop talking.
Examples, examples, examples: Tie as many topics as you can to examples from the audience's world that they will recognize.
Rehearse, rehearse, rehearse. You don't have to be perfect when you present but you won't get it right the first time, either. Don't let your audience see your first time.

And, as long as I have your attention:

Let me recommend a great article on structuring effective presentations. It was written by Martin Shinn (who is a wonderful human being) for the Management Insights newsletter that I edit for Learning Tree International. I realize that I promoting one of my own projects here (and you'll have to register/provide your e-mail address to read it). But it's still a great article.

Reading or read

The Poems of St. John of the Cross by Willis Barnstone (trans.)
Fado Alexandrino by Antonio Lobo Antunes

Tutorials, or They won't do what I say (but that's alright, neither do I)

2010-02-21T20:19:00.000-05:00

I was editing an article for a programming magazine. The author had got to the part of the article where the reader was walked, step by step, through the solution the author was proposing. The author did a great job of describing how to implement the demo described in the article.

Which, of course, was useless to the article's readers.

You know this is true: Just think about how you use tutorials. You wait until you need to do whatever the tutorial describes (i.e. you wait until you have a problem) and then work through the tutorial. You don't, however, follow the steps in the tutorial. Instead, you pervert many (most? all?) of the steps in the tutorial to solve your problem. Guess what? This is what everyone does.

Authors don't seem to believe this, though (even though that's how they use tutorials). Instead, authors seem to believe that readers will take time out of their lives to work through the tutorial--as the author wrote it--to achieve the demo's goals. In other words, author's believe that readers will do something the reader doesn't need to do, do it right now, and readers will do that in order to achieve something that the reader will throw away as soon as its done.

Seem unlikely to me, too.

So how do you support the 'real world of tutorials'? There are four key things you need to do:

1) Never write a tutorial that demonstrates something or proves that you weren't lying somewhere else in your document. Only bother to write a tutorial if, when the reader is done, readers will have accomplished something they will actually want to keep. And give your tutorial a title that reflects what the tutorial will deliver, not what tool the demo uses. A great title is "Formatting Two-Level Bulleted Lists"; a bad title is "How to use the Formatting Menu"

2) Make every tutorial standalone: The reader isn't going to be working through a series of tutorials; the reader will be going directly to the tutorial that gives them what they want. In the prologue at the start of the tutorial (the part between the title and step 1) tell the reader what they need before they can do step 1. A goal-oriented title and a prologue that describes the prerequisites work together to tell the reader whether your tutorial will get them from where they are to where they want to be.

3) Explain how the step works--"the how" of the step. Readers need enough information about the step to make intelligent decisions about how to modify the step in order to achieve the reader's goals. Omit explaining "the how" of the step only if it is so painfully obvious to your audience that it would be insulting to explain it (e.g. most audiences, when working through an application's Wizard, won't need to be told why they must "Click the Next Button"). Don't, for instance, write "Select the Invoices Table"; Do write "Select the table with the information you want to include in your report (e.g. the Invoices table)".

4) Provide feedback for virtually every step. Because readers will be modifying your steps there is always the chance that your reader will veer off on some dead-end path that will lead to disaster. Let the reader know what they should see/get if they've done everything right.

Don't think that you can omit providing feedback because you've written the step so well that readers can't misunderstand it. Misunderstanding is only half of what can go wrong: readers mistype, misread, mis-select--they make mistakes. Feedback not only tells readers they understood your step correctly, it also tells the reader that they did it right. As with discussing the point of a step, only omit feedback if the result of the step is painfully obvious to your your readers (e.g. most readers won't need to be told that, if they select an item in a list on a computer screen, that their selected item will be highlighted).

None of this new, of course. It's all discussed in John Carroll's book "The Nurnberg Funnel." It's a great book--you should read it.

I have a half-day course on writing effective tutorials that I do for my clients. At the end of one of these sessions, a participant said that she had realized that "tutorials aren't instructional tools--they're enabling tools." Exactly right. I wish that I'd said that.

Let's pretend that I did. Thanks.

Reading or read

Salem's Lot by Stephen King
View with a Grain of Sand: Selected Poems by Wislawa Szymborska
How Do I Love Thee? by Elizabeth Barrett Browning
To be Continued: American Sound Serials 1929-1956 by Ken Weiss
The Shadow of the Wind by Carlos Ruiz Zafón

Writing Questions, or Stop me before I query again--Please!

2010-02-15T09:33:00.001-05:00

I got swamped by work and haven't posted for two weeks (or read much, either). In between work, Jan and I also moved my youngest son home from college and celebrated Valentine's day (I know: whine, whine, whine). Over those two weeks, I did do some some software development but most of my time was taken up with some instructional design.

Actually, with a small part of instructional design: Writing multiple choice and short answer questions.

AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAARGGGGGGGGGGGGH!!!

Don't get me wrong: It's not that I don't enjoy crafting multiple choice questions. But after generating three or four hundred questions my brain is starting to go numb. Fortunately, my client got the original deadline moved and I got a break over the weekend (hence, this post). But there's still about 100 questions left to generate and I'll be back at that tomorrow. You may be able to hear the screams.

But all of this work, of course, got me to thinking about effective testing. The first issue to ask of any test is whether the questions address the objectives of the training. It turns out that (at least for me) this is a considerably harder goal to achieve when generating questions after the content is created by someone else.

In the ideal instructional design process, you create your objectives for the training, create the tests that will prove that the participant has achieved those objectives, and (finally) write the content/create the experience that will allow the participant to pass the test.

In real life, I don't do it that way. When developing training material, as I generate the content I get smarter about what I'm writing. As a result, I often go back and modify, extend, or even drop some objectives. Rather than re-do the questions/tests after generating the content, based on the final set of objectives, I do most of the work on the questions/tests at the end of the process. I still do a pretty good job of generating tests in that process.

However, I don't do NEARLY as well when I come in at the end of the process when someone else has generated the content. Part of the problem, in generating questions for someone else's content, I feel obligated to provide questions for content, even if the content isn't tied into one of he objectives. My assumption is that students will feel obliged to study every page in the textbook so it's my obligation to provide a question to justify the strudent's effort. This is wrong-headed of course: just because it's on the page, it doesn't mean that i have to test for it unless it addresses the objectives of the course. I think that I identify too closely with the student.

The nice thing about working for other people is that I get feedback. My client's ultimate customer (the person my client is producing the instructional material for), it turns out, has a style guide. Some of the restrictions that the customer had in their style guide were:

No negative questions ("which of the following is not")
No "None of the above/All of the above"
No questions where the answer finishes the question by providing the end of the sentence

The only one of these dictums that I had a problem adjusting to was the ban on "None/All of the above." My concern with "All/None of the above" are those tests when the only time this answer appears is when it's the right answer (i.e. when "All of the above" is always the right answer). Generally speaking, if I use "All of the above" in a test, I will ensure that the answer appears two or three more times as the wrong answer than as the right answer. Other than that concern, a blanket objection to "None/All of the above" seemed odd to me. But, hey, it's a style guide issue: I doubt that the test takers care one way or another.

I noticed that the customer's review of my questions sometimes fell into what I call the "knowledge fallacy." Often, when reviewing multiple choice questions where we know the answer we critique questions by simultaneously assuming that the student knows the answer and doesn't know the answer--that the student knows as much as we do while still being a student.

For instance, on one question with four potential answers, I had two of the answers in one format (e.g. "verb-noun") and two in a second format (just a noun). The correct answer was in the first group (answer "b"). The reviewer commented that, because the second set of answers ("c" and "d") were in a format different from the correct answer, the student could ignore the second set of answers.

This is true: but only true if you know that answer b is correct. If you don't know which answer is the correct one, the realization that the answers are in two different formats does you no good; if you do know the right answer....well, then, it doesn't matter if the answers fall into two groups.

Last note: In the same way that I think that the most important person on the writing team is a representitive of the audience, I often think that the real test of a multiple choice test would be to have someone completely ignorant of the subject take it. If that person does better than just guessing (e.g. if, on a multiple choice test with 4 answers for every question, the test-taker gets better than 25%) then you have a problem. But that leads to another question: If, under those circumstances, the test-taker does worse than 25% does that mean that you have a really well-designed test or a really unfair one?

Reading or read

The Little Man: Short Strips, 1980-1995 by Chester Brown
Get a Life by Philippe Dupuy and Charles Berberian
The Book of Disquiet by Fernando Pessoa and Richard Zenith
Second Space: New Poems by Czeslaw Milosz

Identifying the Product, Or The most important part of any plan stands the greatest chance of being overlooked completely

2010-01-30T07:29:00.001-05:00

If you had a great product that did something wonderful, wouldn't you tell people? Wouldn't the wonderful thing your product did be, like, the first thing you'd tell people? If you were advertising a sales wouldn't one of the things you'd want to tell people is what your (cheaper) products did? Apparently not.

I review software for Visual Studio Magazine and, as a result, I'm constantly scanning new product announcements to see what's coming out. A lot of the time, I can't figure out what the package does: I often get a list of the new features added to the product but no mention of the package's purpose in life. Sometimes I can't even figure out what the new features do.

I can see that, in the product's accompanying documentation, it might not make sense to spell this stuff out: By the time people buy the product, they probably know what the product does. But in a press release sent out to the general public or on the first page of the website, you can assume that a sizable percentage of your audience doesn't know what your product does (at least, not yet). I've found either that there's no mention of what the product does or the mention is buried in the text a surprising amount of the time.

Well, it's surprising to me.

So here are two rounds of "What does this software actually do?" based on samples of material that I've received or found (names have been changed to product the guilty):

1) Fred v2.0 Is Available Now!

In data centres around the world. We even let you test and choose the fastest data center for your particular location! See for yourself why dev teams around the world choose Fred v2.0 every day.

Fred v2.0 Now! Videos

Take a tour of the Fred v2.0 hosted solution with our resident IT director. Learn why Fred v2.0 can deliver premium hosted performance all across the globe. After watching the overview (left), check out the Quickstart (below). If you like what you see, take advantage of the free Fred v2.0 trial. Experience for yourself why so many teams are choosing Fred v2.0!

2) Impressive Development - Limited Time 50% Discount

Programmers worldwide have supported Impressive Development and our products for 20 years. We wish to return that support by making our tools more obtainable. Therefore, for a limited time, the price of all Impressive products and upgrades have been reduced by 50%.

Reading or read

A Texas Cowboy by Charlie Siringo
A Hero of Our Time by Mikhaild Lermontov
Angle of Reposeby Wallace Stegner
Too Close to the Falls by Catherine Gildiner

Synonyms and Modifiers, or Why your English teacher isn't helping now

2010-01-27T06:15:00.000-05:00

I'm still obsessing about the "effective" that was used in the technical writing manual I discussed some weeks back. It's not that I'm opposed to using things like adjectives or adverbs or think that writers should just use nouns and verbs (though I've always thought that "See Dick run. Run, Dick, Run" was a kind of poetry). It's just that technical writing (writing to explain) is different. It's different from business writing (which is often trying to persuade or record facts) and different from creative writing (which is often evocative). In technical writing all that matters is clarity: Does the reader understand what you're trying to say.

Obviously, to achieve clarity, there are things that you must do: use the reader's vocabulary, make it clear to the reader what your topic is (what you're talking about), and ensure that the reader has enough background information to tackle your new material (either because the reader for your writing brings this with them or because you've provided it in your document).

There are a bunch of things you should not do, also--primarily, don't use modifiers or synonyms. If the author of that technical writing manual had decided to avoid using adjectives and adverbs unless absolutely necessary then he/she/it wouldn't have written the words "effective manual". Instead, the author would have to describe what an effective manual would look like--and supply some criteria for other writers to know when they were doing a good job.

And, as long as I'm complaining about modifiers, let me point out that negative modifers (no, not, none) are especially awful. The clarity value of a sentence with two negative modifiers is a negative number. This sentence with two negatives
Don't exit Word if you haven't saved your document.
Isn't nearly as good as the positive (or, at least, non-negative) version
Save your document before leaving Word.

Synonyms (using several different words that mean the same thing) are even worse. When you put a modifier into your document, the reader knows that you probably meant something. When you start using multiple words to mean the same thing, how is the reader going to know that "computer", "machine", and "server" are all referring to the same thing. In fact, if the reader believes that you're choosing words for a reason, the reader should assume that you mean different things when you choose to use different words. By using synonyms you could send the reader on a wild (and pointless) hunt for a meaning that doesn't exist.

I blame high-school English teachers. Or, more exactly, the impact of high-school English teachers. Teachers, in an effort to increase your vocabulary and make your writing more evocative, encourage their students to use modifiers and to use a wider variety of words. But technical writing is different: use modifiers when you have no choice (and know exactly what your reader thinks the modifer means) and don't use synonyms at all.

Reading or read

Medea and Her Children by Ludmila Ulitskaya
The Rohan Master: A Book of Hours introductions by Marcel Thomas, Millard Meiss, commentary by Marcel Thomas
Unmapped Dreams: The Charottetown stories by J. J Steinfeld

Striking Construction Workers, or The one rule for getting people to read your stuff

2010-01-19T10:52:00.002-05:00

This weekend, when I was driving home from Texas with my wife after doing some software development work with a client, I saw a sign that said "Hit a Construction Worker". It was a Saturday so there were no workers around which, I thought, was going to make it that little bit more difficult for me to actually run over a construction worker. Then I read further down the sign where it told me that I would incur a $15,000 fine if I actually did hit a construction worker. I was some disappointed.

My intent is not to complain about the sign's ambiguous heading because there's a more important point here: The author of this sign wrote from the point of view of the author's client (what we would call the Ministry of Transportation up here in Canada): what was important to the client went first--"Don't Hit Our People." Had the author written from the audience's point of view (i.e. my point of view) the sign would have had "$15,000 Fine" as it's title--then it would have gone on to tell me how to avoid incurring the fine. I'm really not interested in hitting (or not hitting) construction workers--I am keenly interested in not incurring a $15,000 fine.

Obviously, I read the whole sign so I'm probably just quibbling. But it was a reminder of the One Big Rule in technical writing (as I've said before): if you want people to read your stuff, make sure that you're writing about what's important to those people (and not what's important to you).

Reading or read:

Anne of Green Gables by L.M. Montgomery
Prairie Nocturne: A Novel by Ivan Doig

Rude Words, or %#&@#!

2010-01-10T23:32:00.003-05:00

I was watching BBQ PitMasters, a Discover channel reality-tv show (or 'docu-series') that follows some pit bosses around the competitive BBQ circuit. One of the regulars is Myron Mixon, a man who swears so frequently and casually that--on the show--there are seconds at a stretch when his lips are moving but no sound is coming out of his mouth. Which got me to thinking about dirty words, the taboo words that you (normally) leave out of technical writing.

Like everything else, taboo words are driven by your audience rather than anything innate in the words: "Dirty words" are only dirty to a particular audience. And, even then, the words are only offensive to that audience at a particular time or in a particular place.

For instance, time changes offensiveness. The "C word", as we now call it (and I'm one of those people who find the word embarrassing to use) is a great example. The word was in common usage (and, apparently, no more offensive than "penis") up until the 1700s. Then people stopped using the word for awhile (who knows why). When people picked the word up again, it was as an offensive word. "Ods bodkins" (a euphemism for "God's little body") used to be very offensive. Now it is not only no longer offensive, it will actually cause people to laugh at you if you use it.

Geography also affects offensiveness, even among people sharing a common language. Apparently, in Scotland, a sizable percentage of the population uses "the C word" as a term of approval (at least, that's what I took away from reading "Trainspotting"). A friend of mine who grew up in Canada used the word "fanny" when telling in a joke in England and discovered that, while Canadians use "fanny" to as a euphemism for buttocks, Brits use it as a substitute for "the C word." I don't find the word "bloody" offensive but, 10 or 20 years ago, I was able to shock a cousin-in-law who grew up in England by using it.

What is constant about taboo words is that they be emotionally satisfying. This means that taboo words are not necessarily used in a logical or even reasonable way. In "The Stuff of Thought", Steven Pinker points out that "The f***king cat" is not "a cat who is f***king." Yet we find it emotionally satisfying to use the word even though we don't wish the cat to be doing it (it's not really a bad thing to wish on the cat). The reason, Pinker suggest, relates back to the "Ods bodkins" issue and the way taboos change over time.

"Damned", like "ods bodkins" is (or was) an offensive word on the basis of religion (provided, of course, you're Christian--people don't find terms from other people's religions either offensive or emotionally satisfying: even Protestants and Catholics often have different taboo words). Not long ago we would have said "That damned cat" meaning "a cat who is damned"--which is a bad thing and was emotionally satisfying. Over time, we've moved from religion-based offensive words to sexually-based ones (the reasons for which I'm not going to speculate on). In order to get the emotional satisfaction we need out of our taboo words, we removed "damned" from "That damned cat" and popped in "f***king"--which, while not a bad thing, is emotionally satisfying (at least, currently). That emotional satisfaction is paramount and trumps logic or sense.

The replacement of "damned" with "f***king" isn't the only change we've seen in taboo words related to sexual matters within in my lifetime. I read "The Moving Toyshop" by Edmund Crispin, written in 1946, and was shocked (!shocked!) when the main character referred to the woman who cleaned his house as a "slut." Sixty years later, I assume that a modern Brit would call a woman who cleans his house as a "char" or "charwoman"--or even a "cleaning lady": we've lost the ability to use the word "slut" to refer to cleaning staff. Pepys used "slut" in this sense the middle 1600's and, I grant you, it's possible that using the word to mean "char" was already out of fashion when Crispin used it in his book (the book is intended to be funny). But, even if Crispin intended to be funny with "slut" in 1946, I suspect that, today, that's no longer possible.And I won't discuss another book from England written before the Second World War where one of the characters had "recently given up whiskey and fags."

And, by the way, while I've been using the British for examples many of our offensive words aren't particularly Anglo-Saxon. "Piss", for instance, comes from French and Latin ("pissare" and "pisser").

What does this have to do with technical writing? Not much, except the usual one: everything is driven by your audience--including the meanings of the words you use. I'm not suggesting that you throw away your dictionary. But what the dictionary says about a word isn't nearly as important as what your readers say. And, if the very meanings of the words are controlled by your readers, think of the impact that they have on the topics you choose, the way you organize your material, the way you explain it, ....

Facilitation, or What I really do

2010-01-03T10:43:00.002-05:00

I've worked for clients who've brought me in as a technical writer and expected me to figure out what needed to be written; I've also worked for clients who brought me in, assigned me a "tech guy" and expected me to figure out what needed to be written. Both assignments are based on the idea that I was hired because I "write well." It's hard to explain to my clients that both of those arrangements create the wrong team for the job.

I mentioned Joe Boyd in an earlier post (he's sort of a personal hero) in reference to using the OODA loop. A different part of Boyd's career provides a shining example of what the "right" team for a tech writing assignment is.

In the early 60s Boyd was a member of an group called the "Fighter Mafia" who had tremendous influence on the development of the F-15 (Eagle), F-16 (Falcon, informally called the Viper), and F/A-18 (Hornet--Navy/Marine) fighters. That influence grew out of Boyd's Energy-Maneuverability (EM) theory which provided a way of describing and comparing the performance of fighter aircraft in mathematical terms. Fundamentally, the theory took a limited number of features of an aircraft (weight, the difference between thrust and drag) and generated the "power" of the aircraft at any velocity. Aircraft with lower weights, higher thrust, and lower drag would have higher power ratings at any velocity than heavier aircraft with lower thrust or higher drag.
To put it another way: The highest performing fighter plane would consist of a pilot strapped to an engine: low weight, high thrust, low drag (as long as the pilot didn't sit up, at any rate). Not surprisingly, the program that the Mafia participated in (and that resulted in the production of the three fighter planes listed earlier) was called the "Lightweight Fighter Program."

I do have a point and I am getting to it.

At the start of the development process for the fighter that became the F-15, the USAF had been concentrating on creating interceptors--fast climb or fast flight aircraft--to take out nuclear bombers. The replacement of nuclear bombers with ICBMS devalued interceptors. The USAF had also been looking at engagements where fighter pilots might never actually see the enemy and only engage at long range with missiles. However, the feedback from the Vietnam war indicated that close range fighting was still the primary form of air combat. Coupled with the move away from interceptors, this meant that the ability to dogfight become more important than speed, ability to gain altitude, long range firepower or even targeting enemy aircraft at a distance.

For dogfighting, what the pilots wanted was faster transients: The ability to change speed, altitude, and direction quickly. With the EM theory, Boyd (working with the mathematician Thomas Christie) came up with a way to express those desire in a way that was meaningful for the engineers designing planes. Boyd and Christie established a way for the engineers designing planes and the pilots who would be flying those planes to communicate.

Effectively, Boyd and Christie (a fighter pilot and a mathematician) found a way to describe what pilots wanted and do it in terms of gaining and losing energy (which is what engineers understood). Pilots could predict, based on the entry speed and altitude that an enemy aircraft was at when entering a maneuver, what the aircraft's speed and altitude would be on exiting the maneuver. If the pilot could transient horizontally (low drag) and vertically (high thrust to weight) faster than the enemy then the pilot would be able to out maneuver the enemy and "get inside" the enemy's OODA loop. Eventually, the enemy pilot would find that nothing they could do would improve their position.

Don't give up on me: I've finally gotten to my point.

As much as I respect Joe Boyd, it's doubtful that he could have derived the math in the EM formula without Christie (it's also likely that he couldn't have proved the math without massive amount of computer time that he used without authorization). It was the combination of a practicing subject matter expert (Boyd) and a technical expert (Christie) that made the change possible. It was the result of two people from different fields creating a common form of communication that resulted in dramatic changes in the USAF.

As a technical writer, this is also my job: To facilitate a means of communication between the tech guys (subject matter experts) and the audience (customers/users). My expertise is in finding a way for these two groups to talk to each other--not to "write well" (though I do that pretty good, too). Because of my experience in software I can, on occasion, dispense with the tech expert and count on my ability to interview the experts as the mechanism for getting the technical information.

What I can't do without is having one or more members on the team who will actually be using the results of my work: end users. And, strangely enough, end users are often the hardest people to get assigned to the team. "Oh, you don't need them," my clients say, "They don't know anything. They haven't even touched the product yet." What my clients don't realize is that we need these members of the audience because of what I don't know: the world of the reader. While my clients are often likely to elevate a "tech guy" to the role of technical writer they'd be far better off to elevate an end user to the job: the end user is more likely to find a way to communicate with the tech guy than vice versa.

And, by the way, Joe Boyd wrote the first manual on jet fighter combat, so he was a technical writer, also.

For a great book on Boyd's contribution to military strategy see Science, Strategy, and War: The Strategic Theory of John Boyd.

Reading or read

The Shadow Catcher: A Novel by Marianne Wiggins
The Collected Stories of Gogol by Nikolai Gogol

Service, or A good topic for Christmas

2009-12-27T12:47:00.006-05:00

In the technical writing course I wrote for Learning Tree I steadfastly avoid providing a definition for technical writing. Instead, we provide a purpose for technical writing: "technical writing helps people to do things or to make a decision". Concentrating on the 'why' helps clarify what matters in technical writing: the audience, the people you're serving.

One of my sons (Jason) brought up an example when he was home for Christmas: He's preparing a pamphlet on tracheotomy. The hospital where he works currently has a pamphlet on the topic but it's aimed at people who are going home with a tube in their throats and focuses on how the patient (or the patient's caregivers) should care for the equipment. As a nurse, Jason recognized that this pamphlet was unhelpful for his audience. Jason's audience wanted to know what having a trache meant to the patient's prognosis, what the patient can/can't do, what will happen next, what the patient will/won't be able to do then. Jason's proposed pamphlet serves that audience.

Poor technical writers serve themselves. Great technical writers serve others.

Reading or read

Visionaire No. 55: Surprise by Steven Klein, Sophie Calle, Cai Guo-Qiang, and Andreas Gursky
The Wasp Factory: A Novel by Iain Banks
Titus: The Illustrated Screenplay by Julie Taymor, William Shakespeare, and Jonathan Bate
Inventions by Leonardo da Vinci
The King's English by Betsy Burton
The Pocket Paper Engineer, Volume I: Basic Forms: How to Make Pop-Ups Step-by-Step by Carol Barton
An Odyssey in Print: Adventures in the Smithsonian Libraries by Mary Augusta Thomas

Churches as Business, or How does your church compare to the one in Acton?

2009-12-20T17:58:00.006-05:00

I found this while googling for the address of the Immaculate Conception church in Stratford, Ontario. It serves as a reminder as to why technical content should never be automatically generated:

   Catholic Church in Stratford, Ontario
   In the industry "Catholic Church" in Stratford, are 3 companys listed.
   2 "Catholic Church" of these companies are rated as good, 1 "Catholic Church" companies in Stratford, are rated as acceptable. If you are one of this "Catholic Church" signup here to start your "company press release room" and get in touch with the Stratford people.
   Of the Stratford residents, 45% where generally satisfied with the domiciled Catholic Church last month. Compared to Acton in Ontario, Stratford had 38% more successful order executions of "Catholic Church" but 14% more unrated order executions. (Facts based on own polls)

   Reviews on Catholic Church Blog of Ontario
   No Reviews on industries yet. Be the first to write a review!
   Immaculate Conception Church, Rectory was rated as good by a Stratford citizen.
   Saint Joseph's Church was rated as good by a citizen.

(sigh)

Reading or read

Hell House by Richard Matheson
The Fetishist and Other Stories by Michel Tournier

Reference Manuals or, The Best Friend a Technical Writer Could Have

2009-12-13T12:37:00.005-05:00

So I handed in some course material recently to a client and they passed it onto a customer. The response fro the customer was: "You didn't cover this" and "You didn't mention this."

So it was back to the usual discussion:

Who do you think your audience is for this document? (the response is, usually, "Everyone")
What do they do? (If the previous response was "Everyone" this is where the wheels fall off)
How would the material you want to include help the audience do what they do? (And the response is often something like "Well, I think readers need to know this. Background, you know. General inforamtion.")

I shouldn't complain in this case, though: The customer really did have a pretty good idea of who the audience was and what the audience did. What they got stuck at was the "Well, I think they should know this" stage. They were getting pretty stubborn about it, too.

So we started listing off all the scenarios where the customer felt this document would be helpful to the audience. Again, to be fair, the customer did point out some information that I should have included to support a particular scenario (I had missed the scenario entirely and only included the rest of the information for the scenario because it overlapped with a bunch of other scenarios!).

But, other than that case, most of what the customer wanted to include wasn't relevant to any of the audience's scenarios. Usually, at this point, the client sees the light and moves on to complaining about other things (usually: grammar and vocabulary).

This customer didn't. They had a concept of their audience that reflected the customer's view of the information. The customer was passionately interested in this stuff and thought the audience would be too. They wouldn't recognize that the audience was only going to read what they absolutely needed to--what the audience felt they needed to know to get their job done.

Fortunately, I had a back up plan. "How about this? " I said, "Why don't we create a reference or a background document? We could send that out with the manual and the audience could refer to that. We could put this material in the reference manual." The customer bought into that.

There are, at least, two great things about a reference manual:

Reference manuals are generally easier to write than a "real" document because a reference manual isn't driven by any scenario (heck--it frequently isn't read at all). You can just toss stuff into a reference manual and organize it using some arbitrary scheme (e.g. alphabetically)
The customer usually runs out of buget/schedule before you get to the reference manual and you never have to write it all

So that's what we're doing (and I bet I never have to write it).

Reading or read

The Torrents of Spring by Ivan Turgenev
Myths and Legends of Russia by Aleksandr Afanas’ev

Getting Read, or The First Step in Solving Any Problem is Assigning Blame

2009-12-06T16:48:00.007-05:00

In my last post, I was complaining (as usual) about modifiers used as "weasel" words: one of my client's clients, rather than give their writers some real direction in creating technical documents, told them that documents had to be "effective", "comprehensive", and organized "logically." My feeling was that these words gave writers no direction on how to do their jobs and no way for writers to check to see if they had done the job well.

But it does raise the questions: "Shouldn't technical documents be effective, comprehensive, and organized logically"?

Well, yes. Of course. But the problem is that these words don't mean anything--or, rather, that they mean too many things to provide any real direction. All of these words have to be given narrower definitions that are relevant to the job of writing technical documents.

For instance, look at "effective". For me, the first thing that's required of an "effective" document is that it actually be read. Amazingly enough, often "getting read" isn't included in the definition of an "effective" technical document. This is despite the fact that "getting read" would be one of the easiest things to check (call 10 members of the audience, ask if they had received a copy of the document, ask if they'd read it, cross-check by asking some questions based on the content of the document). When I suggest to my clients that "getting read" is a good start on defining "effective", I'm usually told that if the document isn't read, it isn't the author's fault. Well, then, whose fault is it?

Apparently, the reader's.

This attitude isn't without it's benefits. To begin with, by shifting the blame to the reader then, as an author, I don't have to do anything to solve the problem. This is good for me but bad for the organization. Besides, if I keep churning out material that no one reads (like this blog) I'm going to have a very negative attitude towards my job eventually.

So what can I do to get my document read? I doubt that the following list is comprehensive, but here's a good beginning:

Does the title promise to deliver something that someone actually wants?
Does the opening paragraph describe what reading this document will do for the reader?
Is that something that the people who have this document actually want?
Since no one reads these documents start to finish, do the documents headings/graphics/structure allow the reader to find what they may want when they need it?

Getting the document to the right readers, I admit, might not be my problem (but I bet that it is). The rest of the items in the list are certainly my problem. And, you've probably noticed, that last item starts to provide a definition of what a "logical" organization of the material would be: Something that allows the reader to find what they need when they needed it.

So "getting the document read" is my problem. And, quite frankly, I'd prefer it that way. If it's my problem then I can do something about it. If it isn't my problem then I can't do anything about it--I'm a victim. I'd rather be a writer than a victim.

Reading or read

Burridge Unbound by Alan Cumyn
The Photographer: Into War-torn Afghanistan with Doctors Without Borders by Emmanuel Gilbert
Sum: Forty Tales from the Afterlives by David Eagleman
The Hellbound Heart: A Novel by Clive Barker
Batman: Arkham Asylum (15th Anniversary Edition) by Grant Morrison
A God Strolling in the Cool of the Evening: A Novel by Mario de Carvalho