Friday, July 31, 2009

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?"

Monday, July 27, 2009

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.

Wednesday, July 22, 2009

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.

Friday, July 17, 2009

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.

Monday, July 13, 2009

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)

Tuesday, July 07, 2009

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!