Miscellany

A day in the life

Tom Johnson has an interesting post on Quick Reference cards that has double value. For one, it gives good advice on what to do and what to avoid. More importantly, though, it is a great snapshot of what a technical communicator's life is like. I highly recommend it to my academic friends to share with your students, especially those who have not yet started working in the profession. It's not a depressing snapshot, but it does provide a splash of reality in the face.

Shhhhh

In the never-ending cube versus office and office versus home discussions, I often hear the argument for the need for a quiet place in which to concentrate. For a lot of my career, the people who invented the stuff I documented have worked in the chaos of common work areas with couches and foosball tables. But to document their output seems to require quiet and to edit that documentation requires greater quiet.

I have no beef with any of that, but it reminds me of an observation I have made about sports, namely that we are wildly inconsistent with our expectations of crowd noise. For example, in baseball the pitcher throws the ball ninety miles an hour at the batter and puts all kinds of curves on it, but the crowd is hysterical "Batta, batta, batta, suhwiiiing batta." In tennis, the server throws the ball to himself and we are all "Quiet, quiet, quiet, everyone, he's SERVING."

In golf the ball isn't even moving and the player is trying to put it into a hole in the ground (not very likely to be dodging around) and again, "Quiet, quiet, quiet, everyone, he's PUTTING." But a quarterback has to hit a moving target while monster-size opponents try to give him a concussion and again, the crowd is screaming.

No point here, just a pithy, Friday morning observation. Life is good these days.

Conferences and such

OK, I just got my last set of slides off to Joe Welinske for the WritersUA conference, which is on March 29 to April 1. The presentation is "Architecting UA Topics for Reuse" and I'm pleased with how the it came out. After attending the Atlanta STC chapter meeting last week, I realize that there is still a lot of Fear, Uncertainty, and Doubt (FUD) around single sourcing. My presentation uses DITA examples, but I think the principles will be useful regardless of what tool someone uses.

One of the examples I use is a recipe for a cheese grits casserole that I made this weekend and used as a base for my crawfish etouffe. Oh my! It's worth coming to the conference just to get that recipe!

STC conference is in Atlanta in May. STC has extended the early bird rate to help with the economy. I'm doing a presentation on use cases with my boss. Hope I don't screw up.

I went to a 20 year anniversary celebration for the TCOM program at Southern Polytechnic State University. I am an alumnus of that program, a former faculty, former member of their advisory board, and still an occasional adjunct. There was a "here's what they looked like" slide show going in the background, and here are a couple from my academic days:

Doing part of my doctoral studies at the University of Manchester, England


Professor Mike in his office


And this one from the anniversary party itself:

It's Good to Be a Tech Writer

It's not me, it's you

I'm speaking at WritersUA conference in Seattle (March 29-April 1). One of my topics is "Managing UA Projects with Spreadsheets" in which I explain why I broke off my long-time relationship with MS Project to go with Excel as my tool of choice for managing user assistance projects. It includes a full tutorial that will put attendees in an exclusive club: folks who can do pivot tables in Excel. Hope to see some of you there!

It's not me, it's you

Scavenger Hunt

The more I look at the Atlanta Summit host city web site the more impressed I am with Brian Snead and Al Hood for a job well done. Among that, the cookbook, and the host chapter reception, I'm so proud of how we will be showing our Southern hospitality. Still some things to do, Atlanta STC members, you'll be getting an e-blast soon.

Just to make things interesting, I'll give away a free copy of our chapter Summit commemorative cookbook, Fixin to Eat: Some South for your Mouth from the Atlanta STC to the first commenter who finds where Phylise Banner and Andrea Ames are mentioned on our host city web site. (Council members who contribute to the web site are disqualified.)

Happy hunting!

Atlanta Host City Website

Check it out!
The Atlanta STC chapter has posted its host city Web site for the STC Summit. We are starting to get geard up and revved up. We are in the final stages of editing a cookbook of our favorite Southern technical writer recipes, e.g., Cut and Pasta Garden Salad, to share with our visitors. It will include extra tidbits such as tips on speaking Southern. The following in an excerpt:

Bless your heart
This is the most delicious of Southern phrases. When said in a kind way it means that you are doing the best you can in a tough situation. Example: “They’ve got you doing the Help with ForeHelp 1.2? Bless your heart!”
When said in a mean way, it means you’re just too stupid to know better. Example: “You sent the VP an e-mail demanding that the technical writers’ platforms get upgraded before the developers’? Bless your heart!”

Bless their hearts award #09-3

Scenario
This award goes to my ubiquitous user, me, who demonstrates that sometimes the user really is stupid, no really!

I signed up for Skype, the VoIP application, so Tom Johnson could do an interview with me. I had heard about it but had never used it, so I was sort of insufferably pleased with myself over being with it. I told my wife that she was "like so yesterday" and that I had grown. She told me to pick my socks up off the bathroom floor. (Thirty-six years of marriage fosters this kind of crystal clarity in a couple's communications.)

At any rate, this week I started noticing that lots of Web sites had Skype-friendly phone numbers. Example:


As the week went on, I found I was noticing these more and more. I thought, "Funny, once you become aware of something, it seems like you start noticing it everywhere." After several days it dawned on me: I was noticing it everywhere. Part of installing Skype means that it causes your browser to display phone numbers this way. Can I say business model?

Lesson learned
Sometimes the user makes stupid mistakes or stupid assumptions, and there is nothing in your design or your user assistance that can stop that. It's OK. Your application doesn't have to be fool proof, just try to make it so fools don't hurt themselves. Keep the error messages friendly and maybe take a lesson from my wife:

Bless their hearts award #09-2

Scenario
I needed to change my e-mail client password for the 16th time and for the 16th time could not figure out where to do it. So I went to Help. I searched on "password" and clicked the first topic in the list, named "Change Password." My expectations were high. I got this:



There is not a lot to changing a password, and the Change Password screen in this application is very well designed and easy to use. (It even tells me the rules for an acceptable password.) The only reason I can think of someone going to Help for "Change Password" is exactly the scenario I was in, namely, where do I do it?

Lesson learned
Three good rules for user assistance:

• Don't document the screen.
• Don't document the task.
• Do document the probable information gap(s) that could stop a user.
  

Podcast

I did a podcast for Tom Johnnson who blogs at I'd Rather Be Writing. It was a lot of fun chatting with Tom--I'm a big fan of his blog.

Tom posted his own notes on what he got from the podcast.

Just when I ought to be getting cynical...

... I go to my local STC chapter meeting and there are over 50 attendees! So much for a dying profession and a society that has lost its relevance. So what gives here?

First off, a dynamic programs manager, Jen Collier. Last night's event was a progression, six presenters in three 15-minute time slots. Pick the three you're most interested in and rotate. The topic was Instructional Design, a perennially popular topic with technical communicators, perhaps trying to break away from traditional writing or just interested in broadening their skill set in a tough economy.

Speakers were a mixed bag of university professors, consultants and business practitioners--even had an old guy from IBM ;-) This was pure grass-roots STC like its hay-day in the 90s. As a matter of fact, I saw some of my old fellow classmates from Southern Polytechnic State University.

Good pre-marketing too. Getting the word out is important.

Just got me pumped. STC rocks and I'm glad I have a professional society that brings me into contact with peers who believe learning doesn't stop on graduation day.

New Column in UXmatters

I have a new column out today in UXmatters that talks about how the economic meltdown could reshape our approach to writing user assistance.

Get your head in the cloud

In an earlier blog I talked about the importance of understanding your product's business model when deciding on a user assistance strategy or architecture. "Cloud computing" and its cousin Software as a Service (SaaS) bring home the differences a business model can make in how you design user assistance.

Let's talk about a conventional software business model: We build it, you buy it (license model). Think of Microsoft Word. Do you think Bill Gates worries about how many documents you write with it after you buy it, whether or not you use Mail-Merge, or running headers? Not really, he's got your money, and to get more of it, he essentially has to offer more features and sell you an upgrade.

Let's say that Microsoft changed its business model for Word, and instead of buying a license that lasted forever and installing the software on your personal computer, you accessed a hosted version through your browser (can you say Google docs?) and did one of the following:

• paid a monthly fee based on the number of features you were signed up for (feature-based pricing)
  
• paid by the number of documents you saved (transaction-based pricing)

Should it change the way they write or deliver Help? Well this is the way products are going (the business models will be more like those for cell phones) and I think it will make a BIG difference in how we write Help.

When I was a UX designer for CheckFree, we had a similar situation. CheckFree is a bill pay application for Web banking and they get a cha-ching every time someone pays a bill online. Do they care if you pay one bill or ten bills a month? Darn-tootin' they do!

(me saying "darn tootin'")

I think the role of user assistance changes dramatically when you shift to a usage fee-based model and becomes one aimed more at sustained or progressive user adoption. That means that documentation needs to emphasize the use and value of contracted features so that users renew those features (sustained adoption) or points out opportunities where the user could benefit from unused features or increased use of pay-as-you-play features (progressive adoption). See my article Fattening the long tail through progressive user adoption to see how we applied user assistance in that strategy at CheckFree.

As more products go to a SaaS or transaction-based model, think how user assistance can improve feature renewal or adoption. Because in this economy, I'd much rather calculate my value add as part of a revenue stream.

Bless their hearts award #09-1

I plan to start awarding designs in user assistance that I feel are well-intentioned but wrong. The purpose is not to ridicule (OK, ridicule a little) but to show how best intentions are not enough to make a good user assistance experience. The following screen capture is from an non-disclosed calendar application. Note the tool tip/Alt tag.



The problem is that it describes the icon when it should have explained the icon. I have no idea why this icon is on that entry or what it means. The description that it is an icon of a person waving his hand does not help the sighted reader, nor does it work as an Alt tag for a blind reader. Neither knows what it means.

The writers knew that an icon needs an Alt tag and provided a very accurate one. Bless their hearts.

Technical Writer as Playwright

I read this headline on my news feed this morning:

"INSTANT VIEW 4-German jobless posts first rise in nearly 3 yrs."

Actually, I read it several times trying to get it to make sense. I almost had to manually diagram the sentence to parse out its meaning. First, ignore "INSTANT VIEW 4." I read the article and it shed no light. I suspect there are a series of these INSTANT VIEW articles in the publication and this one came after the third and before the fifth. I'm guessing on that.

The real difficulty I figured out was that "post" and "rise" can be verbs or nouns and I was interpreting each one incorrectly from how it was being used in this sentence. This is a common trick that clue writers for crossword puzzles use. After mentally diagramming it, I realized that it said:

[subject] German jobless [/subject] [predicate] [verb] posts [/verb] [object] first rise [/object] [adverbial phrase] in nearly 3 yrs [/adverbial phrase] [/predicate].

My problem when I first read the headline was I had parsed it as:

[subject] German jobless posts [/subject] [predicate] [verb] first rise [/verb] [adverbial phrase] in nearly 3 yrs [/adverbial phrase] [/predicate].

Duh! Well that was a lot of mental work to read a headline! It was further complicated by the odd pairing of subject and verb of "jobless posts..." Try to imagine that. It's hard to because it breaks Joseph Williams' caveat that good sentences are like little plays; the actors should be nouns and the verbs should be what they are doing on stage. Imagine this play instead:

"German jobless rate rises for the first time in 3 yrs."

I can only guess what a machine translation would do, but I suspect that my rewrite will come out a lot better than the original.

The lesson is that Help is read in snippets. Avoid ambiguous parts of speech and make each snippet a good little play that you can easily imagine being acted out on stage.

Because I can tell you I put a lot more work into reading that headline than our users will put into reading our Help.

Bring It On!

I spent a lot of my holiday working on my January column for UXmatters, which I just sent to my editor this morning. I spent a lot of time on it because it is really my strategy statement for my own professional survival and our collective professional survival as user assistance writers in the upcoming new economy. Some highlights:

User assistance groups that survive will do so by doing the following:

• reducing documentation costs
• improving the relevance of the content
• integrating documentation more closely with the product’s user interface
  

Recommitting to user centered design will be evidenced by the survivors in the following ways:

• Starting their research by talking to the product manager and not the developers. The question of the new economy is not “How does the product work,” but “What do the users hope to accomplish with this product and how does that support our business model?” Other questions will be “How do the users measure their own success and how will they evaluate us?”

• Building use cases that focus more on when and why users interact with the system—and less about how. Emphasis needs to be on context, “Why/when would the users go here, what are they trying to achieve, and how will they know if they achieve it?”
  

• Writing documentation primarily for users who are in the middle of something. Users go to the documentation when they are stuck in their own tasks and get out of the documentation as soon as they feel unstuck. Survivors will analyze user tasks for information requirements and decision points that might stop the user’s task flow. Solutions in the new economy will be minimalist and designed to get the user going again as soon as possible. Writers who succeed in the new economy will know that ultimately the user’s solution is in the user interface, not in the Help.

• Integrating user assistance into the user interface. Because the solution to the user’s problem is in the user interface, that’s where the user assistance belongs. User assistance will not be apparent to the user in many cases; it will be just another aspect of the user interface.

• Basing their information design decisions on real user data, such as usability testing and contextual inquiries. We have ignored the data in front of us for two decades—users don’t read the documentation—but this new economy has rung the bell and we must now pay better attention.

The column will give some practical advice on gathering user data that informs user assistance design to deliver useful user assistance. It also will present my effort to redefine myself as cute (assuming the editor does not cut my MOOPOP mascot). I'll post a link to the column when UXmatters publishes it.



MOOPOP = Moments of Opportunity, Points of Pain.

Meanwhile, happy new year to all. Fasten your seat belts and hunker down for interesting times. If we are here a year from now, it will be because we changed and adapted to deliver greater value at a lower cost.

What's in your backpack?

My buddy Miranda Bennett apparently shares my life philosophy of "Anything worth doing is worth overdoing." She wanted to get more exercise so she took up backpacking on the Appalachian Trail. You go, girl.

Someone in the group she joined was helping her sort through her backpack and gave her the following observation, "Your gear is your fear." Apparently, it's an esoteric principle known to backpackers and essentially means that whatever you're afraid of will be reflected in what you overpack. So if you're afraid of getting lost, you might have four maps, two compasses, and a GPS. Afraid of being wet? Two ponchos, galoshes, and five changes of clothing.

Every now and then I get that old "fight or flight" reflex at work. I doubt if I'm unique in that. But I'm a technical writer, and no one is chasing me with a hatchet and there are no lions hungrily walking our halls. So I have to ask, "What am I afraid of?"

If that happens to you, look at your gear. Not now, it won't work. Wait until you have that adrenaline rush that says get the hell out or stand your ground swinging. When that happens, take a serious look at your gear, that is, the artifacts, books, tools, and other stuff you have surrounded yourself with. You could also check out the emotional baggage you like to haul around as well.

Keep what you need, put some of it away, and then walk your trail.

Thanks, Miranda!

The snarky technical writer

Who knew that Lewis Carroll and Henry Holiday understood the world of technical writing?


I don't know what more accurately describes our world, the flying pigs or the tormentors. Take the link below for a fun read.

Fit the Fifth

For a few moments I was special

Those not following national news, Georgia had the last contested seat in the Senate up for a run-off election. Well, to make a long story short, I GOT A CALL FROM BARAK OBAMA! That's right, the president-elect called me. The only problem was that I couldn't get a word in edgewise, he just talked and talked as if he wasn't listening to me.

Well, at least he called. I wonder if I need to put him on my holiday card list now.

Hey, Atlanta, let's do the math

Many technical communicators cannot afford to attend a conference every year, not because of the registration fees, but because of the associated travel and hotel costs (which typically exceed the price of the conference). The STC conference will be held in Atlanta in 2009, and for local good old boys and gals, this is a great opportunity to attend the premiere conference for technical communicators without having to cover the travel expenses.

If you are not already a member of STC or if you are wondering if you will renew, look at the additional savings you get if you attend the conference as a member:

Non-member Early Bird registration: $1095

BUT:
Classic Membership: $175.
Member Early Bird registration: $795
Total cost: $970

By joining or renewing your membership, you save $125! And you get all the other benefits of STC membership.

I can't remember any other time when our profession has had so many exciting opportunities and challenges--this is the year to ramp up those professional skills and contacts. I hope every technical communicator comes to Atlanta for the conference, but we local professionals should take advantage of having the conference right here. Go to the STC Web site and join or renew your membership today.

Better me than Fido?

Every morning I see the following message on the body wash container in my shower: "Not tested on animals."

I'm glad that they didn't abuse animals to develop my soap, but on the other hand, it means I'm getting it before the dog does. I like that they don't do "experiments" on animals, but I also think that at the very end, right when the scientist is about to give it the "OK, Mike can use it" seal of approval, he would say, "You know, Fido here could use a bath. As long as I think this is safe enough for Mike, why not give the old pooch a scrub before signing off on this."

Truth is, Fido probably could use a bath.

Will Write for Metamucil

I almost started today's blog with "I'm getting old" and then decided that's not true. I am old. I tried my best not to get old. Physically I tried to avoid it by drinking and smoking and not exercising, but that didn't work (at least not yet). Professionally I have dutifully tried to keep up with the trends: I DITA, I Wiki, I blog, I tweet, I have a translator on my blog, and I have a page on FaceBook. I also have a pair of bell-bottoms but that doesn't make it 1970 again. (I don't really have a pair of bell-bottoms, that was just a literary device.)

About nine years ago, I was giving a talk on Web page usability at a CDC conference and a gentleman in the audience asked a question about how to make his health Web site for young African American males more engaging. I thought about it for a minute and then gave him my best counsel: "Don't take the advice of a fifty year old white man."

I am feeling the same way about technical communication in general these days. I am steeped in a literary world view that is grounded in the static page. I grew up reading books, papers, and magazines. I did not work with text on a computer screen until I was in my forties--and then it was green screen command-line word processing where you had to actually print the document to see what it looked like.

Keith Lang dedicated an entire blog post to a rather blistering critique of my latest column in UXmatters. My biggest "ouch" response came to this paragraph.

The article is like bad help. It’s too long. It’s too dry. It has no narrative, and it’s written for the kind of people that like to read manuals. I’ll admit it, I’m one of them, but I’m aware I’m the small minority. The pictures are boring. It has no characters, story, or SEX to it. And it’s text, text text.

Not surprisingly, Keith is quite a bit younger than I am, but it reinforces a truth I have come to accept: I am ill equipped to write for an emerging segment of the marketplace.

But that doesn't mean I'm used up like a worn-out number two pencil stub (my favorite simile these days). But it does mean that I need to reevaluate where and how I add value.

For example, Keith included what he called a"nice example" of a built in help video:
It is very nice. A couple of questions: What does this video do to your translation costs, assuming it has a sound track? And how well will the image of a young woman with exposed bra straps play in conservative cultures such as with Muslims? (See my earlier blog about the BBC article in English and Arabic.) Maybe Keith isn't thinking about global markets. After all, his blog does say about comments: "here's how to have your comment approved and published: - Make it in English (my only language)." Sort of says, "If you don't speak English your voice is not welcome here." So maybe part of my emerging role as an elder is to remind the Keiths of our profession that cartoons and cool need to translate across wide cultural boundaries, and input needs to be open to diverse cultures, some of whom might not write your language well.

I'm not picking on Keith, I have have encountered similar gaps before with designers I know well and I respect a lot. People like me, that is, ones with an ingrained world view of communication-as-words, need to bring in designers who have grown up with a more interactive experience with communication channels. If nothing else, they are more like the market place than I am.
But this does bring up the core question of this blog: What is the role of older technical communication professionals like me?

Well, I don't think I should just shut up altogether (although I should shut up a lot and listen more--but that's been true for forty years). But what value do I bring to the party that could help my younger colleagues be even more successful with their innovations? Some suggestions:

• I think I understand the business model better at times than they do. I can help them focus on how their ideas add value not only to the user experience but to the success of the enterprise that pays their salaries.
• I value sustainable processes more than they do. I can help move their innovative ideas into the factory and make those nifty things they do scalable.
• And my somewhat conservative technical communication style probably still plays better in highly technical, complex problem spaces like configuring firewalls than a video or a cartoon would. And that style translates efficiently across cultures and languages.
  

I should probably try to get a job with a high-tech global company.