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

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

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

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

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

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