How to make me stupid

Technical communication is essentially story telling on one hand and sense making on the other. I've noticed (suffered at the hands of) several patterns involving numbers that obscure both.

Consider the following question, "How much does widget A weigh?"

Bad answer: "You have to understand that it will be different in different situations. If it is the blue techno-widget, it will be 30 pounds, but if it is the red techno-widget, it can be as low as 20 pounds depending on if it is a model D, which is 20 pounds or a model C which weighs 25 pounds because it has the heavy duty battery."

Huh?

Better answer: "Twenty to thirty pounds depending on the model and battery type."

Common mistakes when talking about numbers

Here are common mistakes I see when people talk technical with numbers:

• Combining numbers with conditional statements. That's the mistake in the previous example. I'm having to hold too many variables in my head before I can get closure on a declarative sentence. Lead off with a simple declaration followed by exceptions. Another acceptable answer would be "About 25 pounds." That relates a bit to the next common mistake.
• Not rounding to a reasonable level. I sit in a lot of budget discussions where we are essentially discussing estimates and guesses and I am forced to comprehend and store numbers like 23,462 when 23,000 or even 20,000 is sufficient. Many people do not understand the rule of significant figures, that is, an answer cannot have more significant figures than are warranted by the input accuracy. For example, 10 volts divided by 30 ohms does not result in a current of .333333333333 amps. It results in .3 amps.
• Giving algebra problems instead of answers. "Q: How much does widget A weigh? A: Ten pounds more than widget B." Great, widget A weighs x + 10, solve for x.
  

There is a scene in Othello where the generals argue about how many ships are in the approaching armada. The bottom line, stated more eloquently by Shakespeare is "It's a shit-load of ships." In other words, providing the exact number is less important than contextualizing the impact.

I qualify as an offshore resource

Gasp! I can't live with the scandal anymore. I WAS BORN IN KENYA! I'm not a native US citizen.

Social Web: This old dog finally gets it

I think there should be a "Get Out of Purgatory Early" card for folks my age who try to keep up with Social Media. I signed up for Twitter and Facebook a while back to see if I was missing anything. I must admit I was pretty baffled by it all for a bit.

Tweets like "Just turned the computer on, man am I tired," left me wondering why the tweeter felt that the world was waiting for that update. Facebook people were poking me and taking quizzes that told everyone what kind of Simpson character they would be.

Huh?

A sliver of light

My first inkling that there could be something useful lurking here happened at the Atlanta STC Summit. As the host chapter, we arranged for the Atlanta Braves to have someone at our hospitality booth one morning to sell block tickets for a Braves game that night. The day he was to arrive, it occurred to me that we had not publicized this in any way. I asked Lisa Pappas, who is way cooler than I am when it comes to social networking, if she could tweet that the rep was coming on the #tag we were using for the Summit (I barely knew what a #tag was). She did. At one point I took a break from the board meeting to step out and apologize to the rep for the lack of advance publicity and found him packing up early. He had sold the allocated block!

Hmmm. That was useful.

More illumination

I then started to notice that I was using Twitter like a news aggregator because people I was following would recommend interesting Web articles they had just read. I recently noted the following pattern of tweets, going from great to lame:

• Great: There an interesting article on such and such at http:...
• Good: There comes a time in the lifecycle of a document you have to shoot the writer and publish the damn thing.
• Lame: I had oatmeal for breakfast.

I had been judging the social Web based on the abundance of "oatmeal for breakfast" tweets and posts I had been seeing.

Let there be full light

Recently, however, the major light bulb went on for me. I was starting to feel a lot more connected with contacts I usually saw once a year at a conference. The odds that I would pick up a phone or shoot an email to someone like Phylise Banner or Brenda Huettner if I needed help on something was now an order of magnitude higher than if I were not following them on Twitter or friends on Facebook.

It's as if I were linked into a social network! [a Mikey major Duh! moment]

I also found that I could link with folks I was having somewhat adversarial relationships with in STC. As an officer, I've taken quite a bit of heat over some unpopular decisions and problems lately from well-meaning and articulate critics. Twitter and Facebook have given me the opportunity to interface with some of these critics at the level of home-brewed beer and love of musical instruments. Their confrontations have been reduced from my total perception of them to being just part of a broader understanding of who they are. Hopefully that has gone the other way as well.

Suddenly the faceless and voiceless critics have become people who brew beer and play music. Does that make me now more willing to listen to them? You know, I think it does! At least it makes it easier.

I've said it before, "Oh brave new world..."

You Can't Handle the Truth

I was in a staff meeting recently where the topic was "What do you need to know in order to do your job better?" I can summarize the general theme in one word, "Truth." What is the real schedule, what are the real priorities, how is the project really going?

It seems truth is a rare commodity going both ways on the communication chain. People were equally concerned that they weren't getting the truth from management and that management wasn't being told the truth.

I'm not telling stories out of school; namely, because this is the same discussion I have heard at every software company I have ever worked at. I suspect it transcends industries as well.

• I was at an international conference in Leeds, England, on Learning in the Workplace where the keynote speaker asked "Have you noticed that the purpose of a project status meeting is to hide the status of the project?" He got a standing ovation.
• I used to teach project management at Southern Polytechnic State University and I would tell my students, "If you say the project will be six months late, you will be fired, but you can be one month late six months in a row and nobody bats an eyelash."
• Projects stay in green status until a few weeks before release and then go into red--all of a sudden the code doesn't work.
• Projects change status or iterations end not because criteria have been met, rather, because their due dates have arrived.

Part of the problem is an inherent dislike for delivering bad news. Partly as CYA and partly because genuinely we want to please others. We accept the pleasant fiction for the very reason that it is pleasant.

Part of it is that we treat mistakes like crimes and punish those who make them. Therefore, mistakes become things we must cover up.

But I think a major contributor is the whole myth of project management. We estimate dates and resources when we know very little about the problem space, let alone the solution, and then those dates become holy unto themselves. We beg others to lie to us (sometimes even insist on it). "How long will this take?" "Three months." "Not good enough, give me a better estimate!"

Let me offer a radical proposal: What if projects were open ended? What if a product didn't ship until it was ready? Instead of dates, we had feature and performance specifications, resource allocations, and release criteria. "Nothing would ever ship," might be a reasonable rebuttal. That is pretty telling in and of itself.

I know the devil is in the details, but it might be time to rethink our current model of design and development.

Lost in Space(s)

The APA has returned to its requirement that two spaces follow a period. See the first bullet in Chapter 4 in the Chapter-by-Chapter section or their "What's New" page.

The technoscribe blog-o-sphere is a twitter!

Those who have insisted on keeping two spaces in spite of the fact that ALL modern word processing technology accommodates the necessary spacing, take heart. Once again you are right.

Those currently getting therapy from a psychologist take warning--those who direct and publish the research of that practice are apparently still doing their work on typewriters. Expect the following edgy articles to be showing up in their journals:

• "The Steam Engine: Advance or Anxiety?"
• "Being Gay in America: The Role of Happiness in a Modern Culture"
• "Media Overload: Do We Really Need All Three Channels?"
  

Time for a new look

Some days a blogger just needs to feel pretty. Seems I'm into changes these days. My wife and I went to the movies this weekend. You need to understand how my wife and I go to the movies. We go and leave together, but rarely actually sit in the same showing. She saw "The Ugly Truth" [chick flick] and I saw Public Enemy (Johnny Depp with a way-cool scar on his face; did I mention I have a scar on my face?). Hers started about 30 minutes before mine so I hung out in the mall for a little before going in. Walking around, I saw it, the perfect hat--kinda a mix between a pork pie, a fedora, and a golfer's hat. Of course, they had the brim all wrong, but I was able to rework that (turned up all around). I bought it and sat in my theater feeling its soothing karma settle over me as if it were a wet towel wrapped around my head on a hot day. I've started growing my goatee back with a thin mustache (gratis to some skin cancer surgery this winter) and I was feeling "edgy." Well, my wife came into my show after hers let out and looked for me. She sat down next to me, looked at the hat, and all I got out of her was "I left you alone for twenty minutes."

I'm celebrating by changing the color scheme of my blog site. For those of you wondering what life is like when you reach 60; this is it.

G2G

A genre of technical writing that doesn't get a lot of attention is Geek-to-Geek (G2G). In that genre, highly technical people are communicating to other highly technical people. Most of the discussions in technical communication deal with transferring technical knowledge from experts to the average Joe.

Professional technical communicators need to be very careful when inserting themselves into G2G scenarios. Some examples:

• I had an intern once work on a specification document our engineering group had written so that customer IT folks could configure their applications to exchange data with our application. She took out the word "argument" everywhere it occurred because it sounded confrontational.
• I had a layout/graphics designer make a training manual I had written more "user friendly" by changing "120-volt (AC) solenoids" to "120-volt air conditioned solenoids."
• I was reviewing a document a software developer had written that was to be sent to other software developers in the company and found his excessive use of multi-layered indents to be distracting. I was just about to comment on it when another developer looked over my shoulder and said, "Cool, he's using FORTRAN formatting rules; that makes it so much easier for me to follow."

By no means am I saying that professional technical communicators have no role to play in G2G, but I do think our role changes a bit, and I think some of the rules we normally follow need to be modified.

I was recently involved in a G2G situation, and I noticed some differences between that genre and G2J (Geek-to-Joe). A developer in my company had written some documentation about how to use an open standard reporting tool to issue reports from one of our products. The readers would be developers who worked for our customers. Some differences:

• Technical writers (uh, me) like to write in generalities; geeks like specifics. We talk about how to change parameters, they describe how to change a specific parameter.
• Geeks want to show how things work--often describing what goes on under the covers; technical writers don't feel they need to prove the procedure does what we say it does, or even explain why it does. For example, in his discussion of parameters, the developer told the reader to run a specific report, then had the reader change a specific parameter, and then run the report again to see the effect.
  

Seeing how the developer wanted the reader to run a report, make a change, and run the report again reminded me of an experience I had years ago when I was a trainer at Nordson Corporation. Nordson is a company that makes glue applicators for packaging equipment (a hardware environment completely on the opposite end of the spectrum from the software world I now live in, but geeky none-the-less). We had a new product that glued cartons with a "sift-proof" seal--very useful if you're packaging powdered products like laundry detergent. The only problem was that we had only one field technician who seemed to be able to install one of these things correctly. So they sent me into the field with him to learn what he knew and to pass that on through training to the other technicians.

We got on site and the technician got the glue guns and sealing bracket all bolted on. He showed me a bolt that affected alignment of the sealing surfaces and explained: "Here's how I adjust this," and he turned it fully clockwise and ran a carton. The resultant sealing job looked awful. He then turned it fully counter-clockwise and ran a second carton. It too looked awful, but in a different way. He smiled and said, "See, now I know what effect it has, so I can now adjust it." Well he went on in this way through about three other alignment controls and in half an hour had this machine cranking out perfectly sealed cartons.

Hard to put into a training module, but a good insight into how geeks think and work.

Some things to consider when intervening in G2G:

• Geeks need to know underlying principles that will let them predict cause and effect.
• Geeks like examples.

Places we can add value:

• We know how to write instructions.
• We know our company's legal and style requirements.
• We know how to produce and distribute documentation efficiently.

It might feel a little secretarial, in so far as we should give the SME a little more leeway to dictate what information is important, but we still add a lot of value when we help make these G2G documents more "customer-facing."

But don't just roll over and play dead--for example, I took out the parts where we were telling users to run reports to see that changing the parameter really did affect the report--but in G2G, the geeky writer probably understands the geeky user better than we do. Be aware of that and try not to break what could be a perfectly clear explanation by recrafting it for the average Joe, who will never read it.

Cop vs Consultant

As a member of the STC certification task force and a former member of the Body of Knowledge committee, I have been interested for a while in understanding the core value proposition for engaging professional technical communicators. The essential question is "How is a technical communicator better than an engineer who writes well?"

I've read a lot of reports, essays, blogs, and e-mails on this topic. One of the bullet points that got to me was that professional technical communicators understand the legal requirements of documentation. It's not that it didn't make sense, it's just that I have never measured up well in that category. Now that I see it as a differentiator, I'm starting to take it more seriously.

Oh did I mention I work for IBM? I wonder if they care about things like copyrights and trademarks.

The kinda good news is that IBM provides me with a ton of information on my internal employee Intranet about trademarks. The really good news is that they provide a tool that searches my documentation and tags everything that could be trademarked. The tags are read by our output rendering tools and they apply the (tm) and (r) symbols appropriately, as in first use in a topic, not in a title, etc. I just have to do a manual scrub and look for places where their use is not a trademark, as in IBM being used in reference to the company not a product. Trust me, that's a small enough trade off.

It also gives me a tool that looks at all my documentation for word usage and notifies me when I use a term that is not approved or might be used in the wrong way. Most of the suggestions are based on how elegantly certain terms are handled by translators versus other terms with the same meaning.

I mention that as a bit of self-disclosure. I'm preaching that everyone should care about this when probably most already do and many do not have the nifty tool-box my employer has provided me.

But, it's probably worth a mention. Pay attention to the legal requirements and translatability issues, not only in your own documents, but in the documents of other groups like marketing and engineering. It's an area where we add value.

The tough part is doing it without sounding school-marmish (still working on that).

Maybe I'll modify the old "feel, felt, found" approach sales people use to handle objections, as in "I know how you feel; I felt the same way, but then I found..." I'll try "use, used, uncovered".

"I see you use the word following as in '...includes the following:' I used it the same way until I uncovered the fact that most translators will interpret it to mean something like 'group of admirers' when it is used as a noun. I now only use it as an adjective as in '...includes the following features.'"

I know I am trying to move away from my "you're wrong and I must warn the others" syndrome, but sometimes there is value in warning folks when something is wrong.

Teacher vs Educator

Thanks to Marv Jenkins--a great educator-- for passing this along to me.

Lipstick in School (priceless)

According to a news report, a certain private school in Washington was recently faced with a unique problem. A number of 12-year-old girls were beginning to use lipstick and would put it on in the bathroom. That was fine, but after they put on their lipstick, they would press their lips on the mirror leaving dozens of little lip prints. Every night the maintenance man would remove them, and the next day the girls would put them back. Finally the principal decided that something had to be done.

She called all the girls to the bathroom and met them there with the maintenance man. She explained that all these lip prints were causing a major problem for the custodian who had to clean the mirrors every night (you can just imagine all the yawns from the little princesses).

To demonstrate how difficult it had been to clean the mirrors, she asked the maintenance man to show the girls how much effort was required. He took out a long-handled squeegee, dipped it in the toilet, and cleaned the mirror with it.

Since then, there have been no lip prints on the mirror.

There are teachers. . . and then there are educators.

Knee bone connected to ... a new acronym

Some recent thinking about information and media reminded me of a lesson I learned a long time ago during a usability test.

The product was an anatomy software application that presented detailed medical illustrations. There were three primary data bases underlying the product, based on the three types of medical illustrations:

• Layered view (skin on/off, muscles on/off, just the bone, just the veins, etc.)
• Cut -away (as in take a knife and slice it in half)
• Pin-view (as in pull back bits and pieces as if on a dissection table and label the components)

It was a grisly experience, but that's another story.

The user interface was designed around, you guessed it, the three views:

1. Pick a view.
2. Pick a body part.

Want a different view? Navigate up and over and then drill down through the new view to the body part.

Well, it didn't take long for the usability test to show the flaw with that. The user work flow was pick a body part and look at the different views. Classic mistake, user interface was designed to reflect the data structure, not the information needs of the use. Easy fix. (UI fixes usually are.)

Fast forward to today and I see where we can easily make the same mistake regarding information and media on Web sites. Blogs here, professional publications here, academic publications here, forums here, podcasts here.

But users typically do not come into a problem defined around media, as in "I want to see a podcast," "I want to read a blog," or "I wonder what academic research says." They define problems in terms of "I want to know..."

For example, if I want to learn a song, I have to go to YouTube to hear it sung, another Web site to get chords and lyrics, and then often another Web site to get music or tablature. But if my problem is "I want to play Sweet Baby James, wouldn't it be neat to have one place that offered a video of James Taylor singing it, along with links to lyrics, chords and tabs right there? And Google isn't the answer; I'm lazy and want a vetted aggregation. (In other words, I don't want 19 different sets of chords, I want at most two: The ones James Taylor actually uses and maybe a simplied version ala a "fake it" book.

I'm hoping we avoid this misstep with our STC Body of Knowledge and all of the other media we are contemplating. I don't want to go one place for academic articles, another for practitioner insight, and yet another for the social media. Once I say "I want to know about usability," I want the UI to aggregate all the STC assets and present them to me.

I know. SMOCM (pronounced "Smoke 'em"--simple matter of content management)

The Cowboy Way

In case you haven't heard, the economy is tough, and the Society for Technical Communication (STC) is having its challenges--just like a lot of businesses and just plain folk are. Lower attendance at the conference means we did not get as much revenue as we had planned on, membership has been declining, and our investments took the same hits that everybody's 401Ks did. As First VP and member of the board of directors, I have a front row seat to what the cruel calculus of this economy does.

We need to rethink, retool, and reinvent our society to meet the new realities. No shock there, staff and board have been working hard at it for some time. It's just that the economic crisis took away a lot of runway, so we're trying to rev the engines, so to speak, on many changes that need to happen sooner rather than later.

I also have a front row seat to how badly some people act in these kinds of times. I don't think the blame-laying finger pointers realize how counter-productive their negative energy can be. As a volunteer leader finding myself in the middle of circumstances so much bigger than myself, I try to take a mature attitude--shake it off, Mike, stay focused on the solution. Until recently, I've been doing OK at the chin up, stiff upper lip posture.

But I can feel the depression overtaking me and I wonder how others cope. Sarah Palin retires--man, I so get that!

Not the cowboy way, though, and I have to stick to the cowboy way. Shake it off, rub some dirt on it, and stay in the saddle. Do the right thing for no other reason than it's the right thing to do. If I have learned no other lesson about leadership from this, I have learned that.

I'm also learning about followship, and I'm going to try to be more supportive of my leaders, national and business. There is no user guide for this sort of thing (but if there was, it would probably be a PDF buried on the Web someplace--OK my sense of humor is starting to come back a little). They have to make tough decisions, often with not nearly as much data as they'd like. They're stuck with tools and systems they didn't create and that are not ideal for the job. And they can see the solution clearly at times, it's just that they have to move lots of people and entrenched bureaucracies and special interest groups to get there. I'll give them the benefit of the doubt and my support. If I get to the point that I think they are so wrong, I'll quit and go quietly so they can stay focused (in case I'm the one that's wrong).

And in the meantime, if they start moping and feeling sorry for themselves, I'll just tell them to shake it off, rub some dirt on it, and get back in the saddle.

Yippie kay yay!

Collect Underpants

Thanks to Miranda Bennett for posting this on her blog a while back. As I struggle with trying to define what our New Normal for STC will be like, I keep wrestling with Phase Two.

Balsamiq

Shout out to Balsamiq for believing me when I said I had a license but I changed laptops. They sent me a new license (thanks, Val).

Check out their product Balsamiq Mockups. It's a low-fidelity wireframing tool that has an informal hand-drawn look. I have used high fidelity wireframe tools and one of the problems is that people fall too easily into pixel pushing if it looks like it's meant to be a final product.

At any rate, check them out; it's $79 and way cool--and they're way cool!

Online vs. on-line

No this isn't a discussion of hyphenated vs. not hyphenated. It examines the difference between putting a PDF file on the Internet (what I call an on-line document) and having a truly electronic Web presence for that content (what I call an online document). Unfortunately, the two often get bundled together.

I have a UXmatters column called PDF Manuals: The Wrong Paradigm for an Online Experience that highlights my arguments for not putting user manuals on line as PDF files. It deals with the artificial constraints such as page breaks that make no sense in the context of an online experience.

In my blog today, however, I want to focus on other kinds of publications, namely journals and magazines, and the impact of taking them...what? online or on-line.

But first, let's play a mind game. Anybody still remember encyclopedias? What if encyclopedias were bound, NOT alphabetically by topic but by when the articles were written. Is that a better organizational scheme? Not at all! But in essence, isn't that what a collection of journal issues is? With the exception of a few theme issues, the only thing the articles in a volume have in common is their publication date. So if I want to read about Usability, I have to grab a handful of these issues to get to all the articles. Can you imagine trying to read about the Civil War in an encyclopedia and first having to find the volumes that applied--based on when the sections were written?

Because of how journals and magazines were published, this was an artifact of the technology and the processes imposed. It was never a good way to organize content.

OK, so as we go online with the content that has traditionally been in journals or magazines, why would we keep this organizational structure?

Let's take a model I am very familiar with and have a lot of emotional attachment to: Technical Communication and Intercom, the two STC publications. I personally love having them in print for two reasons:

• I like publishing in them and being able to display them on my coffee table--I realized that about myself when I published in the UPA Journal, an on-line journal, and noticed the lack of the "hunter's thrill" in not being able to display my trophy.
• Just having the physical presence of them arriving makes me feel smarter, or at least feel I'm about to get smarter--if I read this issue, and I will, let me just put it here with some other stuff I haven't quite gotten around to reading yet, hmmmm, this one is March 2002, my my time has certainly been flying.

But if I quit thinking about publications for a moment and think instead of knowledge and some realistic contexts of when that knowledge could be useful, journals and magazines just don't seem to be the answer, or their capabilities pale in comparison to what current technologies can do.

OK, let's do the Conan O'Brien thing where we put a flashlight under our chin and someone chants in falsetto "In the year 2000" (Yeah yeah it's well past 2000 but Conan knows a good tag line when he finds one) and see what it would mean to have a truly online (no hyphen) journal and magazine.

I have a question about Usability, maybe a big question like "what is it" or a tiny question like "how do I do a card sort?" I go to the STC Body of Knowledge Portal and enter usability. I'm taken to a web page that has a general overview of what usability is and its place within the practice of Technical Communication. Now I see that I can link to rigorous research articles, practitioner articles, vendor websites, and other websites that deal with usability. I decide to read an article that says it's been peer reviewed and meets the rigor of scholarly research--let's say the abstract associated with the link made me believe it would be of interest to me. I open the article and get a little overwhelmed by some of the research methodology, as in, "Yikes what is an ANOVA?" Wait, a link in the sidebar "Tell me about ANOVA." I take it and get a quick layman's description of what it is and what I should look for as a critical reader. I read the article and it seems to make a lot of sense to me. Wait, here's a comment from a reader that says the literature review missed some important contributions and provides them. Hey! Speaking of literature review, about half of the references at the end of the article have links to the references themselves. And of course, the Amazon.com technique of "Readers who read this article also recommend..." Wow, here's a link to an STC content focus group on usability. Let me check into that as well.

Suddenly, I'm missing my journal and my magazine less. I know as an author, I will not be able to put my contribution on the coffee table and I would be lying through my teeth to say I will not miss that. But publishing should never be about pleasing the author, it should be about serving the reader.

I know as a reader, I must give up the vicarious joy in that others are smart and I will be too as soon as I get time. But now I can get smarter on a just-in-time and as-needed basis because I know where to go when I need to be smarter about a topic in my field.

O brave new world that has such documents in it!


Related posts:
State of the Ark
How Not to Update your Look and Feel

State of the Ark

State of the ark: A phrase I coined (I think) to represent feeling that the technology you are using is so cool when in reality it is like so yesterday.

For example, I got a new phone this weekend that I think is neat because it slides open, and I can display my wife's picture and have a special ring-tone when she calls. Other than that, it just makes and takes calls. Someone wanting to mock my enthusiasm could say "Mike's new phone is state of the ark." It would simultaneously mock my phone and my technology naivete. Sort of like "Bless his heart."

Use and enjoy.

How not to update your look and feel

Mike Hughes, STC 1VP not afraid to embrace new technologies


One of the themes that keeps coming at me as an officer of STC is that STC needs to modernize its image so that it has more appeal to the upcoming generation of technical communicators. Our demographics certainly show that we have to increase our appeal to a younger segment of the industry.

It reminds me of when I was speaking at a CDC conference on healthcare communication and my topic was Web usability. Someone in the audience asked the question, "I'm designing a Website for young African-American males, what advice can you give me?" My reply was "Don't take advice from a fifty year old white guy."

Good advice then, and I'm in a similar dilemma now (only ten years older). I need to recruit people whose skills I really can't judge, and I need to direct work I'm not situated to evaluate. I just have this amusing vision of me and my peers among the board and senior staff (albeit with some exceptions) sitting around saying, "Yeah, this is the stuff that young people want."

The best advice I can come up with is "Use the Force, Luke." Seriously, I need to include younger folks I trust at a gut level who seem to have a good reputation among the demographic I'm trying to reach, and then suspend my own "But that's not how I would do it" reflex.

In fact, it might be a good idea to reject any proposal I like. {sigh}

You're wrong, and I must warn the others

I took a pretty intense course during my doctoral studies that explored different ways we can study our interactions in groups. I learned a lot about myself, and the title of my blog today is the title of the reflective report I wrote. It was the defining characteristic I had discovered about myself that was making the wheels come off in some of my key interactions.

I still have the problem, but I am more aware of it and hopefully self-regulate faster and better when I fall back into it. For example, I corrected my wife last night when she referred to that thing I use to propel my kayak as an "oar." "No, honey, it's called a paddle." I knew what she meant, so why sidetrack a perfectly good conversation? At least it was just the two of us--sometimes I stop the flow of a meeting or presentation to make a similarly useless point. Hopefully not as much as I used to.

Why am I blogging about this?

Technical communicators, as a breed, suffer from a similar hang-up, perhaps more accurately described as "I must copy-edit every document and conversation I touch." Perhaps the worst offenders are The Typo Eradication Advancement League (TEAL), who actually go as far as to deface historical artifacts they feel have been punctuated incorrectly. But there is a little TEAL in all of us.

What's wrong with taking a stand for correct language?

First, by who's definition? I am notorious for getting as much use out of a document as possible, so I get to see myself edited on what is essentially the same article by multiple editors. Trust me, folks, there is not a consensus even among top editors about the best way to turn a phrase. What I change to suit one I must put back to suit another.

Second, it's often idiosyncratic. It's not that what the original person has said is wrong, it's just not how the person correcting it would have said it. Fine, get in on the act when the page is blank and you get to say it exactly as you would like.

Third (and most important) it gets in the way of the conversation and shifts the focus from substance to style. Sure, edit away at a user assistance file that's going out to the public, but we can keep quiet about the typo in the e-mail or worse yet what a person says in conversation.

Here are some questions I am going to try to ask myself more before I say, "Shouldn't that be...?"

• Is it worth the speed bump I am about to insert in the conversation or the process?
• Will it make a real difference in meaning or am I just spraying the bushes to put my scent on them?
• If it's OK with my peers, can it be so bad that I need to intervene?
  

A Day at the Ballpark

The Atlanta STC chapter had a great community-building event: We went to a minor league baseball game as a group. We went to see the Gwinnett Braves (the farm team for the Atlanta Braves). Tickets were $6.00 and parking was $3.00. We tailgated and had a fun time. Great little stadium, cold beer, and a lot of grass I don't have to mow. What more could you ask for? There was one fist-fight over the serial comma rule, but other than that, a good time was had by all. (OK, I'm kidding about the comma rule fist fight, but a good time was had by all.) Thanks, Jen and Rachel for a creative event to bring professionals together in a social context.

Trying not to squander my ignorance

Ah! Convergences.

I am working on writing some high level patterns for what kind of content users need. One of the patterns is "Product Overview" and I was just starting to think about it when...

...all of a sudden I win a copy of Madcap Flare! Now, this is the third time I've won a copy of Madcap Flare, and the first two times I donated them to my alma mater, Southern Polytechnic State University. This one I'm going to keep. For one thing, now that I am sixty, I realize that one day I will retire from IBM and not have access to the Information Developer's Work Bench, so I had better start coming back up to speed on other products if I want to teach/consult/contract.

Also, having a new product to learn will give me first-hand insight into the "new product out of the box" user experience. I have only one shot at using this product for the first time, so I want to notice what's going on in my mind and what information I need.

First, they have a very nice dynamic help pane. Mind you, this is something I usually advise against because the real estate it consumes is very precious, and I argue that UI development will some day take it back or the user will. But there it is on a prestigious product so I'm thinking maybe I'm being a curmudgeon.

I decide to take a 30 minute "tour" (they also have a tutorial, but I traditionally hate those because they make me do a project I don't care about). Tour is working pretty well as they show me what's what, and then very early they do an interesting thing:

They close the dynamic help pane in the tour's example so that they have more room.


Even the Help writers shut down the dynamic Help pane because it takes up too much room! Not only that, but it's one of the first things they teach the user to do.

So it validates my point: Don't put too many eggs in the dynamic help pane basket--it won't be there for long. Have a UA strategy that delivers embedded assistance without the footprint of a dedicated Help pane.

Well, back to noticing what it feels like to learn a new product.

Iron Hoop

I finished posting my novel Iron Hoop to the Internet over the weekend. It's interesting that a blog turned out to be a fairly OK way to post a novel. Not ideal, but free, accessible, and I know how to do it.

I'm not sure what I expect to get from this. If nothing, else, just a chance to tell a story that amused me in the writing of it (ten years ago). Oh sure, an off-the-wall chance that I can bypass the agents who have shown no interest in it in hopes that a publisher or screen writer finds it and likes it. Or maybe I'll win the lottery.

At any rate, I feel like I've got one more thing on my bucket list checked off.

At the heart of every technical writer...

... is someone with dreams of the "Great American Novel" and I am no exception.

I decided to publish my little novella that I have written (Iron Hoop) electronically using the Google blog engine. I will be loading it chapter by chapter over the next several weeks.

It is a coming of age kind of thing about growing up in the Deep South is the early sixties.

Ah the Internet!

Iron Hoop

Why do people listen to me?

And more importantly, why will they listen to you? I find myself mentoring writers who would like to get published or speak at conferences, and I notice that most have the same reticence: "I don't have anything important or new to say."

Yesterday I read my speaker's bio for the upcoming UA Europe 2009 conference and felt quite abashed. (The one in my preconference workshop description was even more 'abashing.') My initial reaction was "I've got to meet this guy." Like those who seek my advice on speaking and writing with authority and influence, my reaction was "I don't deserve those words." It reminded me of the first time I spoke at a WritersUA conference where I had one of the big rooms. I saw my title slide on a screen that was bigger than the flag backdrop in the movie Patton, and I wanted to tell the audience that what I had to say did not deserve a screen that big.

So I pondered all this on my drive to work this morning and asked myself how I had become a pundit. Actually, it's an important question because all technical communicators are in the business of speaking with authority and influence, and often we feel inadequate in the role. Like who am I to be writing about firewall rules in a help file meant for network security professionals?

The following curve came to me on I285 (it was rush hour and traffic was slow). The best part is that I got to see my love of bell curves and Sufism converge.

Click graph to enlarge

Pundits are not the leaders of the pack. In the adoption curve, I've always come into the party pretty late in the game [sound of mixed metaphors colliding], but that is where the pundit adds value. Up to that point, the innovators and early adopters have been tightly focused on details. In a way they are like the blind men in the Sufi tale, each feeling only a part of the elephant. Only someone joining in late can see the elephant as a whole. It is the role of the pundit to say "It's an elephant."

How do the innovators and early adopters react to this? "Duh, no lie, Einstein."

How do those coming behind the pundit react? "Wow, that is so cool, I get it."

The secret is to not compare yourself to the really smart people who have gone before you--that is way depressing, trust me. Instead, look at what you can offer to those coming behind. And incidentally, look at the area of that curve! What? 100 million people who can benefit from technology such and such, and a third are already doing it? That's 33 million folks in line ahead of you. Oh wait, that's 67 million behind you.

So recognize that as a technical communication professional, you're getting involved with products and technologies often at the sweet spot: Early enough to have a sizable audience that's not there yet, and late enough to have the vantage point to be able to see the elephant in the details.

Write about it, speak about it, let yourself get a little recognition for it. Just never quit blushing at the sales hype about you and wanting to "meet THAT guy."

How to improve the UI--really!

A colleague has made me realize that user assistance writers are codependents of bad UI design. Because we explain how the UI really works, we somehow leave our developers and companies feeling like they're "covered" when the users have a bad experience.

We're not covered; the users still had the bad experience. It's just that we can apply the "nanny nanny boo boo, you should have read the manual" defense.

A simple example is the Delete button. Because of bad design practices, it has two meanings in many software applications: "Hasta la vista, baby" as in gone, gone, gone, and "Removed from here and put somewhere else in case you change your mind" as in the Recycle Bin. Because of that ambiguity, we had a discussion at work about the need to explain in the context sensitive help exactly which Delete we meant on a particular dialog box.

But why is the UI using the same word for two very different actions in the first place?

So here is my new challenge. What if Help quit explaining how to interact with the UI and quit telling the users how the system would respond? What if that became the burden of the UI itself to make interactions clear and outcomes predictable? Better labeling, embedded text, useful tool tips, etc.

What would technical communicators do? What would Help do?

For starters, technical communicators could help write UI text. Then we could reserve Help for scenario type of topics, ala how to achieve some business outcome using the product or encourage users to attempt complex tasks by demonstrating their value.

But we have to break out of our codependency first. Part of me likes to document the obvious because it's easy; part of me likes to compensate for bad design because it gives me instant "I add value" gratification.

Sometimes being part of the solution just makes us part of the problem.

New column and lessons from the Dobro

I have a new column out in UXmatters: Architecting UA for Reuse: Case Examples in DITA.

Although I have owned a Dobro-like guitar for some years now, I just now got around to actually "studying" the correct techniques. Man! I had it all wrong. But the experience reminds me of a point my usability mentor, Loren Burke, used to make all the time. He observed that a common learning pattern was:

1. This is easy.
2. This is hard.
3. This is easy.

I see/hear a new song on Youtube or on one of the instructional links and think, "Oh I can play that." I then start to learn it and find that the picking patterns are awkward and the guitar sounds like a pig being tortured. I was three days into a half-minute rendition of "Will the Circle Be Unbroken" and sounding like someone putting thumbscrews to Porky. Then I woke up Sunday morning, picked up the Dobro, and voila! I could play it.

So it looked and sounded easy as a naive novice; it became hard as a struggling novice; then suddenly expertise emerged and it was easy!

So how does user assistance help move a user from the naive "this is easy" to the expert "this is easy"?

I don't have a good answer to that one yet, but I know this: The secret to learning to play the guitar well is to enjoy playing it badly. This seems counter-intuitive, but the point is that you can only achieve the second level of "this is easy" through practice, practice, practice. So you have to somehow enjoy that "this is hard" period enough to keep coming back and eventually work through it.

So how do we convert this principle into a working model for product skills where users do not want to invest time and energy in the "this is hard" phase?

My hope is to figure that out and get rich. In the meantime, I'll enjoy that slide up on the B string to G and the following back roll drone for a while before tackling some new way to make Porky screech.

A Birthday Poem

I am three score years upon this earth
This twenty first of May aught nine,
I pause to contemplate the worth
Of twenty-one thousand, nine hundred and fifteen days of mine.

In looking back at the seeds I've sown
It's clear that friends too few were gendered.
But the worth of those whose love I've known
Makes them all the better remembered.

So now to all who dealt me kind
So now to all who shared their ranks
Apologies if with absent mind
I have been slow in giving thanks.

Wow! What a Summit

I can't remember a more exhilarating STC Summit. Congrats to Alan Houser for pulling off a great event. The two keynotes were delightful and informative--making me excited about being a technical communicator. Unfortunately, my official duties didn't let me take in too many of the technical sessions, but I networked my little heart out.



Some IBMers at breakfast. By popular vote (at 7:30 a.m.) we decided it would be an IBMer happy hour next year. (l-r: Terri Whitt, Robert Anderson, Barrie Byron, Mike Hughes, Lori Fisher, Alyson-Kathleen Riley, Susan Becker, Mark Wallis)


Me with my fellow Fellows from IBM, Andrea Ames and Lori Fisher. It's good to be a Fellow :-)

Use Cases Are Working

Just in the nick of time, as my boss and I are putting finishing touches on our PowerPoint slides for our presentation for the STC Summit "Moving Documentation Upstream with Use Cases." The theory was that if we used use cases as our Information Development user analysis methodology, we could get involved earlier in the development process and even be able to influence design decisions.

We've had some intermediate successes but it has been hard to insert ourselves at the point in the process where we think the use cases can be the most effective. We recently tried with a project that probably comes as close to the perfect scenario: right team, right changes on the UI, good timing, etc. We had one design meeting last week where we collaborated among product developers, UI developers, information architects, information developers, and QA to understand why a user would view system statistics from the home page of one of our security appliances. The discussion last week was productive and helped form a better team vision of what the user would be doing and why (shifting the team from their normal approach of "What data do we have and how do we want to display it?").

This week the information architect ran a collaborative session where he did a sticky notes on the wall kind of card-sorting exercise that started matching "kinds of data we have" to "things the use wants to do with data" (essentially the use case titles we arrived at in last week's meeting). In a word, it was exciting!

The best part was at the end of the meeting where I asked the developers to accommodate room next to the graphs and tables for embedded user assistance to set the context for the user, based on the insights that had come out of the workshop. The developers agreed that at a minimum we could have fly-over text, pointing out that graph sizes would make real estate hard to come by.

I know this might sound trivial, but to be having discussions about what embedded assistance the designers and developers would accommodate this early in the project was HUGE! The fact that we got a concession of any type was MAJOR!

I hope those of you who are coming to the Summit will come hear our presentation and watch our demo:

Moving Documentation Upstream with Use Cases

Date: Monday, May 04, 2009

Time: 3:00 PM to 4:30 PM EST

Location: Hanover AB

Description

How to apply case methodology and structured writing to get information developers involved earlier in the design process and to produce testable information products earlier in the development cycle.

LEARNER OUTCOMES:

• Create UML use case diagrams and write use case descriptions
• Describe a systematic process for going quickly from use case diagrams to user documentation
• Describe the benefits of involving information developers early in the design process

Chase the rabbit down a hole...

And find a time vampire!



All I was supposed to do was fix some capitalization issues with our new DITA build. It was picking up a title attribute it had ignored in previous versions and I just had to edit the Navtitle attribute in about 100 references.

But there was a nitty little anomaly in how the css was rendering some paragraphs. Probably just a tweak needed here. Tweak, tweak, build...hmmm no that didn't get it. Time to move on and do what I came to do: fix capitalization. Oh wait, I wonder if this other little tweak will do it.
...
Two hours later, still renders wrong in some paragraphs and let's see, how many more topics do I need to edit? Oh, the 100 or so I haven't touched in the last two hours.

I should know better; we all should know better. As it was, I kinda got pulled into this quick sand pool by a buddy who had already been thrashing in it for a day. But we get sucked in by this never-ending thread of "just one more thing and it should work" morass.

Lesson learned. That rabbit looks so easy to catch up with when it jumps down that hole.

Be scared of the rabbit that goes down a hole; be very, very scared.

Miscellany

Everytime we pass a restaurant that has gone out of business and been converted into office space, my wife comments that they must have one really great employee break room. Wow! A break room with a walk-in freezer, pizza oven, and deep fat fryer.

Howard Speck added some really great rules to my earlier blog Why did it take me so long long to learn... I especially love "Never argue with an idiot, people watching can't tell the difference." I'm having that one printed on a card and carrying it with me!

The Atlanta STC Awards banquet is tomorrow! My wife is at a business meeting all day which means I will have to get dressed in my tux all by myself.

The STC Summit starts a week from Sunday--in Atlanta!! We have a local chapter cookbook we will be selling that is a MUST HAVE for anyone attending the conference. My favorite excerpt: "You know you're a Southern technical writer if you put in a comma where you want the reader to pause...and spit."

Actor Mug Shots

Click picture to enlarge it.

Why did it take me so long to learn...

• Never write an email response when I'm angry. Waiting 24 hours can mean the difference between a relationship-straining diatribe (and looking whiny) and a rational appraisal of a situation with reasonable recommendations.
• Don't use "Reply All" to show others how smart I am by taking on [whatever, whoever]. I now limit my distribution of "I think you did something wrong" e-mails to the individual. The serendipity is that half the time I'm wrong, and I'm saved the public embarrassment of their "Reply All" that makes that obvious to the world. I took a course in grad school that helped me analyze my interaction style. I titled the summary paper that described my newly found insight "You're Wrong and I Must Warn the Others." If that describes how you interact in groups, you might want to put it on your list of "things to work on." (BTW--I'm still working on it.)
• When having to choose between the best solution (as defined by, uh, me) and a consensus, go for the consensus. The theme of me being wrong half the time applies here as well--the compromise is not such a compromise since half the time (at least) my best solution would have been wrong.
• Don't squander the opportunity to lose an argument.
  

Doh!

It's April Fool's day and Google got me early. I took a link at the top of my email to New! Gmail Auto Pilot

Layoffs

The news this week was that IBM laid off 5000 workers in the US. Some take-aways for me:

• No matter how strong you are, you can't be stronger than your customers. IBM looked at the numbers and said we need to be leaner in the coming year. Anyone watching the news could have seen that coming.
• When you work for a good company, good people get laid off. Why? Because there aren't any bad people to lay off. Those of us who kept our jobs need to reflect on that with a bit of humility.
  
• In a bad economy, avoid specialist roles like "special adviser" or "ombudsman." If you're out there all alone on an org chart, well, it's as good as wearing a target. Avoid being an infrastructure person; try to be writing words someone is ultimately paying for (i.e., user-facing doc).

I got some insight from our director about how this sort of thing works. I'd seen it from the inside before, but his clarity gave me fresh insight.

It starts at high-level management as a dollar amount. "Our income and our burn rate are misaligned by this much, therefore we need to cut x dollars." Payroll is the deepest pocket, so that's where you have to go if x is a big number. Then middle managers do some calculations and x dollars is translated into y headcount. From then on, y becomes "the number." Lower level managers divvy up y among even lower level managers until some sub-component of y is communicated to a line manager who must convert that number into names, that is, actual people who have to figure out how to make mortgages and buy food.

It's a cold calculus and a heartbreaking one that gets more so as the process trickles lower and lower. It probably works because the ones at the top who have to start the ball rolling are insulated from the humanity where the ball lands.

So if you lose your job, take some solace in the coldness; it was never about you and it wasn't because of anything you did. If you keep your job, it doesn't mean you are better than those who didn't, just luckier, perhaps.

May we all be lucky.

Because I said so

A colleague sent me a link to a blog by someone leaving Google. The person joined Google seven years after it had been founded as its "first visual designer." He refers to himself as a "classically trained designer" and contrasts that to the other designers at Google, who had backgrounds in CS and HCI.

It reminded me why I have trouble working with visual designers. I deconstruct his blog to be saying, "It got frustrating not getting my way on the merits of my stated, expert opinion, but having to actually justify and convince non-classically trained people--often being asked to justify my decisions with USER DATA (how pedestrian!)."

I think technical communicators are grounded more in the social sciences and rely less on the kind of connoisseurship I find with visual designers. For example, I'm involved in fewer and fewer discussion where someone says "It just doesn't sound right to my ear." In most discussions I have with technical communicators, they have reasons and research to back up why this combination of words is more suitable than another combination.

Not that I don't work with visual designers who do the same. It's just that with visual designers I'm more likely to encounter the "because I have taste and you don't" rebuttal. (I have yet to get a good explanation for why Comic Sans is a bad font.)

Imagine going into engineering meetings and justifying my suggested changes to the UI labels by saying, "Because I am a classically trained technical communicator." Like THAT'S going to work.

My point is that I'm glad it doesn't work. I don't mind basing my decisions on principles and research that can be empirically validated. It's part of what makes me a professional.

Progressive User Adoption

I have a new column out in UXmatters.com on progressive user adoption. It is based on an article I wrote for the Cutter IT Journal. It shows how technical communicators can expand the value they add to their companies by increasing user adoption within their current user base.

I think it is a good example of how we can restate our value proposition in terms of our sponsors' business models, a theme I harp on a lot in this down economy.

Value

I'm working on a number of fronts around the issue of Value, as in the value of my profession to my company, the value of my department to my division, my value to my department, the value of STC to my profession, etc. A couple of aha! moments for me:

• Good organizations are not cutting stupid programs or laying off poor performers in the face of this economy! Good organizations have already cut their stupid programs and gotten rid of their poor performers. All that's left to cut are good programs and good people, so the rebuttal "We can't cut this program or this position because [however 'they're good' translates]" doesn't mean anything.
• We need to quit talking about mission and vision and talk only about deliverables and value here for awhile. What do I produce and how does it add value; what do we produce and how does it add value?
• We need to articulate how we assess the value [it] adds.
• We then make that assessment the litmus test for every initiative.
  

UAX

I was recently contacted at work to be a member of the "Next Generation User Assistance Experience Council." The person setting up the group was somewhat apologetic over its long title, but I loved it. I thought it told a compelling story. In setting up a folder to start collecting files and such, I named it "Next Gen UAX."

UAX, I like that! UAX carves out a special niche for us in the UX world. I also think it sets up some interesting discussions about what would constitute UAX as a discipline or practice that would be different from just talking about user assistance.

First, I think there are two dimensions along which to view UAX, each with its own set of implications and requirements.

• UAX encompasses how the content of the user assistance supports the user experience with the product the UA supports. Along this dimension we would discuss the usefulness of the UA.
• UAX also encompasses the user experience manipulating the UA delivery channels with things such as navigation, linking, interactions, affordances, pliancy, etc. Along this dimension we discuss the usability of the UA.

So the mantra of a UAX approach is to provide information that is useful in a way that is usable. Ingrained in this approach is a user-centric task analysis that identifies task- or goal-oriented information requirements and the design of a delivery mechanism that optimizes access to that information on an as-needed basis. It also requires an evaluation methodology that looks at how useful the information was to the user and how easily was the user able to access it.

I know this is not a big departure for most of us, but I do think that linking user, assistance, and experience into one semantic unit does shift the perspective in a significant way. It moves us further from being merely writers and more to being developers of information delivery applications. It moves us from looking at Help as a codified body of knowledge about the product as a whole and more as a collection of interventions targeted at specific moments of opportunities and points of pain. We will worry less about "Is this presentation consistent with one the user might have seen elsewhere in the Help" and more about "Does it meet the likely need of someone in this task on this screen?" We will worry less about "Is this complete" and more about "Is this sufficient?"

So, as of right now, I start relearning my craft under the new classification of User Assistance Experience (UAX) with the driving question of "What's next?"

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.