The Doc Whisperer

I could certainly use dog trainer Cesar Millan. Our two-year old labradoodle Jessie is a bit of a mess. She often begs for food, and thinks nothing of resting on The Forbidden Couch. But compared to the dogs featured on Milan's show, The Dog Whisperer, she's Lassie.

The Dog Whisperer is a unique reality-TV program. In each episode, we're introduced to a new insane animal and its even more insane owners. Dogs with a wide variety of behavioral and disciplinary problems are featured. Before this show, I would never have believed a dog could have OCD (obsessive compulsive disorder).

Millan interviews the owners, then instructs them on how to deal with the dog's behaviour, using a combination of leadership, discipline and affection. The worst dogs are taken to Millan's Dog Psychology Center, where presumably the animal shares with a therapist its childhood problems and the fact it just "can't let go" of the doggie treats.

What's most impressive about Millan is how efficiently and professionally he interviews the owners, quickly assesses the situation, and in some cases, is able to immediately correct the problem. Dogs are often transformed right before the owner's eyes.

Dogs vs. Docs

A dog whisperer, therefore, is a trained professional who assesses the animal, interviews the owners, and provides a solution. The definition of a "doc whisperer" is self-evident, but a comparative list is helpful:

• dog whisperers assess dogs
• doc whisperers assess docs

• dog whisperers interview owners
• doc whisperers interview owners, including subject matter experts

• dog whisperers see what the problem is right away and recommend a solution
• doc whisperers do the same thing

• dog whisperers show leadership by implementing the solution
• doc whisperers - ditto

• dog whisperers follow up with the dog and its owners to ensure the solutions are maintained
• doc whisperers follow up with the doc and its owners to ensure the solutions are maintained

Doc whisperers are more commonly known as "senior technical writers", but what's in a name anyway? So if you want to be a great tech writer start whispering....

After all, dogs and docs are very similar: they both need lots of attention, they both can get out of control if not maintained, and they both involve toys, as in:

"Here Rover - it's the latest edition of FrameMaker, with tabbed browsing and better conditional text management."

"Arff!"

Read More

Tech Writing, From A to Wii

My wife asked me if we're ever going to buy a game console. In my worst French I mumble, "Oui". "We're getting a Wii!?!" she cries, " Woo-hoo!" I cannot Undo my misunderstood utterance.

The good news is that Nintendo recently lowered the price of its popular gaming unit. The bad news is that the unit represents only a fraction of the total price. Once you're done adding accessories (such as the Wii fitness board, extra controllers, other games, extended warranties and taxes, you end up with a purchase price approaching that of a small car. But, oh boy, is it worth it.

A brief disclaimer - neither I, nor any of my relatives, friends, or enemies work for Nintendo. However, I sure wish I did.

The Wii is a masterpiece of design, form and function. That's why it's outsold the Xbox 360 and PlayStation 3 combined. I don't even want to discuss the documentation that comes with Wii, which is adequate, but the fact that most users won't even need the guides. (Gulp! No tech writers needed?!)

The I's Have It

The Wii succeeds because it has the magic combination of I's:

• Intuitive - it's easy to use
• Informative - it gives clear and simple instructions as you're using it
• Intelligent - it appears to "learn" from your actions
• Incredible Interface - based on all of the above

A huge factor in the Wii's success is its simplicity. The remote only has a few buttons. The games, aimed mostly at families and non-power users, are generally simple to learn and play. That is, the user does not have to struggle with the hardware or software to learn it.

Am I Making Myself Clear?

Every professional communicator (including us technical ones) can learn from this. Readers should never have to struggle to find the information they're looking for, or understand the information you give them. It should be as clear as glass.

Beyond documentation, technical communicators have a critical role to play in product design. I'm fortunate to work for a company that actively solicits feedback from its employees, and have given numerous suggestions for enhancements to the user interface. No formal training is required for common sense suggestions, such as the fact that every field should have a name, and that the name should be clear and self-descriptive.

Always be on the hunt for superb design and execution, as seen with the Wii. It can inspire you to create great documentation.

Now, back to tennis and golf...

Read More

Catch the Wave

Outdated is a word coined by manufacturers to convince people the shiny new products they purchased six months ago and which work perfectly are now useless. However, once in a while, a new product comes along that really does make the current version practically obsolete. Google Wave could be just such an application.

Google Wave is difficult program to describe, but is essentially a cutting edge communication application that's a combination of email, instant messaging and collaborative editing. Because Google Wave is so different than anything before it, the best way to learn about it is to watch the long video here. The next best way is to finish reading this article.

New Wave Rocks

Google Wave is the name of the latest application developed by Google. Within it you create documents called, appropriately enough, Waves. Waves are XML-based document objects similar to an email thread, but so much more. Instead of writing and sending an email, you create a Wave and then share it with others.

Google Wave was created because email as we know it was developed long before the Internet, the World Wide Web, rich content and multimedia. Traditional email is like putting horseshoes on a Ferrari - painful.

Creature Features
Here are the main features of Google Wave that make it light-years beyond regular email:

• when you type a message, other users see your keystrokes in real-time, character by character; no more "Amy is typing..." messages to wait through, although you can turn off this feature if you wish
• instant and intelligent spellcheck: for example, "It's bean so long" is automatically corrected to "It's been so long"; "icland is an icland" is automatically changed to "Iceland is an island"; these changes are either instantly made, or suggestions are automatically presented in a drop-down list below the word in question
• you can view the history of a message thread using a "playback" feature - this allows you to step through each response as it was received, one message at a time, so you can see who wrote what and when they wrote it
• multiple users can update the original message - all users will see each other's changes in real time as they are typed, in other words, real-time live document colloboration
• a built-in search function - you can search sites, images, videos, and then with one click instantly add the link or photo to your message
• you can easily respond to just a portion of a section in the message, instead of the entire message; new threads are automatically created
• you can easily drag photos onto your message, and rename them, again in real time
• automatic recognition of URLs: if you enter google.com, it is instantly converted to a hyperlink
• you can easily embed videos

Extending a Hand

You can also extend Google Wave by creating extensions for other applications and websites. For example, you can:

• add a Wave to to a blog - updates to the Wave instantly appear in the blog, and vice versa, in real time
• add Twitter to a Wave - the Twitter thread appears in Wave - updates to one appear in the other
• embed various apps, such as a chess game
• create your own "branded" Wave; for example the ABC Company could create a Wave that appears as an ABC Wave, with all of the Google Wave's functionality
• add a "response" gadget - a table with multiple columns: each column represents a response to a question, for example: Do you like cheese? - Yes | No | Maybe; when you respond, your ID appears under the column of that response; to change your response, you simply click another column and your ID instantly moves to that column
• insert a map into a Wave - if one reader zooms in or out, or annotates the map with markup tools, the other users will instantly see the new view or the changes
• add a form: for example, multiple users can collaborate in real time on the construction of a poll; you can be writing the questions while another user writes the potential responses; you can then can instantly send out the poll to all the recipients, and the poll results are updated live in real-time

To Infinity and Beyond...

These features are indeed incredible. But perhaps the most outstanding feature of all is the one demonstrated near the end of the video: real time translation to another language. Using a special translation add-on, you can type in one language and an instant, real-time, word by word translation appears in another language.

When new technology like this comes along, I'm always reminded of two of Arthur C. Clarke's "Three Laws":

• The only way of discovering the limits of the possible is to venture a little way past them into the impossible.
• Any sufficiently advanced technology is indistinguishable from magic.

On the first law: Only by hiring the best and brightest engineers could Google create such an application. But technical intelligence only gets you so far; you have to be a dreamer, a doubter and a rebel. You must believe in the impossible to do the possible.

On the second law: Google Wave certainly does appear "magical". But we have to be careful not to be overwhelmed by the magic. Just because a new product can be used in new and different ways does not necessarily make it more "usable". I'm sure many of us could personally could benefit from such a tool, but we are hyper-combinations of communicators and engineers. Many people might balk at such a complex application. Just because something may be "better" doesn't mean people will use it. History is filled with "better" products that failed for other reasons: price, usability, inability of people to change - the Apple Newton and WebTV are but two examples; you can view more here.

The Wave is scheduled to be released either late 2009 or early 2010. It will be fascinating to see if it succeeds, because it could impact our profession. Think about it: XML-based; collaborative editing; ability to track changes; instant communication - are these not the ideals of technical communication? If the Wave takes off, it could inspire a whole new generation of people to become technical communicators.

And what a Wave that would be...

Read More

He Said/She Said

Here's a word puzzle for you: which pronoun (he or she) would you use to describe a person who has had a sex change? I ask this because I recently read a news article about a female teacher who underwent such an procedure. The teacher now considers himself?/herself? as a man. (Oy - I'm already running into trouble here.) However, the school (a religious one) still views this person as a woman. The author of the article used the title Mr. and the pronoun he when referring to the teacher. Is this correct?

You see the catch-22 here. By using the word he, the writer accepted the position of the teacher, and tacitly recognized the teacher as a man. But if the writer had used the female pronoun, he would have been considered disrespectful toward the teacher. What's a poor writer to do?

Mutant Hybrid
One solution is to create a new type of hybrid pronoun, something like s/he. Not only is this awkward, it has the side effect of offending both points of view. The solution lies the basic principle of technical communication: Know thy audience.

You see, this entire he/she debacle is not the problem: it's a symptom of a much larger problem: trying to write the same information for two different audiences, in a vain effort not to offend either. The two audiences are secular and religious.

Secular Vs. Religious
Let's assume that most people who read non-religious newspapers are secular. So we can safely take the liberal, secular position and assume that whatever someone calls themselves, they are that person. This relates to another aspect of information development.

In documentation, we sometimes have to describe different types of users: basic, intermediate, advanced, and so on. Many software applications will only allow certain functions or screens to be accessed by certain user types. For example, an Administrator will have access to certain modules that a Worker (a regular user) would not.

Who defines these roles? Well, ideally, the person who is working in that role would have to agree, at least on a general level, to that description. Heaven forbid we have a regular user calling themselves an Administrator. That is, the person filling the role helps define the role and needs to agree to the role they are assigned to.

Back to the story - the teacher views himself/herself as a man, and is legally recognized as a man in our secular legal system. So from the secular perspective he is a man. Therefore, the newspaper would be right to use he.

Now, if you are a deeply religious reader, you:
a) don't read secular newspapers

-or-

b) do read secular newspapers, with the understanding that they might "offend" you

-or-

c) read only religious newspapers

So if I was writing about this person for a religious magazine, I would use she, because that word reflects the religious viewpoint. Just as secular writers should not be forced into the religious viewpoint, religious writers should not be forced into the secular one.

That is the essence of documentation: writing with your audience in mind.

And you could easily single-source both articles in FrameMaker. God bless Adobe! (Oops...)

Read More