Archive for the 'Visual/Technical Communication' Category

BREAKING NEWS!!! (i think)

Earlier today, a certain UA development company sent out an email to all the members in its registered database with the phrase: DITA 10-29-08.

Of course, you know who it is, and what they are selling, so there’s no need to tell you. Not being a DITA developer (I know, I’m the last to jump on that wagon), I won’t be able to offer much in either the “zOMG we should be excited !!11eleventy!” or “puh-leeze, try again” camps until we actually get to see and play with a product.

So, in short, I’m not sure what this post is actually about. Is a corporation hoping that I market for them? Is it viral marketing if I don’t publish who it is? Is a post a post if it doesn’t contain any useful information or insight at all?

Therefore, here’s a cookie recipe:

White chocolate macadamia nut cookies
2 cups all-purpose flour
3/4 teaspoon baking soda
1/2 teaspoon baking powder
1/2 teaspoon salt
1 cup (2 sticks) unsalted butter, softened
1 cup light brown sugar
1 egg
2 teaspoons vanilla extract
8 ounces (1 1/2 cups) white chocolate baking squares, cut into small chunks, or white baking chips
3/4 cup roughly chopped, unsalted, toasted macadamia nuts

Preheat the oven to 375 degrees F.

Combine the flour, baking soda, baking powder, and salt in a mixing bowl.

Beat the butter in a large mixing bowl until fluffy. Add the brown sugar and mix together until smooth.

Add the egg and vanilla. Blend in the flour mixture in 3 stages and stir in the white chocolate and the nuts.

Scoop out walnut-sized mounds of the cookie dough and place on a cookie sheet, leaving 2-inches between the mounds. Bake for 8 to 10 minutes, until the cookies are golden.

Remove the cookie sheet from the oven and transfer the cookies to cooling racks. Eat while thinking of DITA-related press releases and odd websites.

Touchscreen interfaces

Tom at IRBW has posted some guidelines on creating online help for touchscreen applications.

It’s interesting timing, as that’s a task that I’ve been currently tackling. If human factors standards are being used, it’s an exceptionally difficult challenge to meet.

I’ll be sharing some lessons learned soon, but I’d thought I’d open it up for discussion first. How about you? Any ideas or thoughts to share?

In related news, here’s an interesting piece of research that was done by NASA - touchscreen usability research in space. Groovy.

monkeyPi’s Law

Recently, I’ve come across several blog posts that have brought up the issue of Technical Writing versus Writing.

At its core, writing is just recorded communication that’s transferred without the use of verbal speech. If you communicate to someone else (or yourself) using a pencil and paper, or a laptop running Office 12, or even a sabretooth tiger horn and a cave wall, you’re writing.

Using this definition of recorded communication, we get a better big-picture view of the world of writing, and it’s a broad vista that includes written words, glyphs, graphics, charts, and so on. Alan Porter eloquently makes this argument:

“Examples of effective communication using more graphics than words are all around us. I spent several years in the aerospace industry, and what’s the most effective and widely viewed piece of documentation in that industry? The safety card placed in every seat back pocket.”

But does that broad vista include communicating something other than safety or technical information?

The problem with current viewpoints
There seems to be a pervasive view that there are two types of writing: “Noble” (or “pure”) and “Non-Noble” (or “technical”). The main problem with that myopic view is that status is immediately connoted. Nobody wants to classify themselves as residing on the non-noble side of the writing world.

What’s worse to me is when excellent, talented people who choose that “Non-Noble” path seem to feel they have to caveat what they do, have to rationalize it somehow. Even Alan Porter, in the same article linked above, did this later in his post:

“I’m proud to be a writer. But I leave being a pure writer to the evenings and weekends. When I’m in the office I try to be a Communicator…”

Am I to conclude that the author leaves “pure” writing at home, and then goes to work? No wonder Tom Johnson works so hard to convince students that technical writing is a worthy career.

Is one form of writing more pure than another? Is one type more noble than another?

I propose a new way to consider The World Of Writing, and because I’m a egomaniacal loser, I’m calling it monkeyPi’s Law of WritingTM:

Writing is recorded communication. If we must classify writing into two categories, then they will be titled: Writing that is Meant to be Used, and Writing that is Meant to be Enjoyed — and they will overlap significantly.

As of now, the notion of “Pure” writing is out.

Writing that is Meant to be Enjoyed
Writing that is meant to be enjoyed might include fictional works, poetry, essays, and so forth.

As we remember that all writing is a form of recorded communication, it’s important to note that even the most creative fictional writers are just as dependent on effective communication as technical writers are. Even the most artistic example of fictional writing still has that requirement hanging over its head. That’s why writers developed rhetorical techniques to communicate abstract concepts like feeling and emotion.

For example, where would fictional writing be without imagery? Consider the sweltering temperature outside in 12 Angry Men, as tempers rose inside the jury room; or the thunderstorm raging outside the cave as Aeneas and Dido gave in to their carnal urges to Juno’s lightning flashes in The Aeneid. If you’re using a method or technique to communicate essential information, you’re doing the same thing someone who writes a technical manual does, just in a different fashion.

Writing that is Meant to be Used
Writing that is meant to be used might include manuals, help systems, reports, proposals, and safety labels.

But good forms of useful writing can be made enjoyable, as well. Technical charts that pay attention to aesthetics. Blogs that, *ahem*, inform and entertain. Help and assistance that helps establish a pleasurable experience for the interface user. There are always ways to enrich the human experience using even the most dry material.

Some will argue that this isn’t true. They may say, “How many lives have been enriched because of Shakespeare’s sonnets, or Hemingway’s tomes?” Countless. And how many lives have been saved and protected because of “Right Lane Must Turn Right,” or “Warning! High Voltage!”? Also countless. I’ll leave the argument of which is more noble as an academic exercise to the reader.

If you write reports, try injecting some tasteful levity into it. Sure, the rules say you can’t do this, but shove the rules. Technical writers always complain that “nobody ever reads reports.” Well, why not make them more enjoyable? In a recent final report I helped write, where we were reporting on the results of a mock-theft experiment that involved human participants — about as dry of a subject as you can imagine — I included a section called Experimenter Anecdotes. In it we detailed some observed oddities among our participants. Some were frankly hilarious, such as when we listed all of the places (normal and gross) we observed our participants hide things, which went from the obscene (orifices) to the puzzling (bologna sandwiches). The section contained very useful information, but was presented in such a way that it served as an island of comic relief in an ocean of dry scientific prose. The client went out of their way to specifically mention that part of the report as being their favorite.

The beauty is in the overlap
The greatest thing about my new law is the ‘significantly overlap’ clause. Here is where all those things go that didn’t have a home under the previous system.

How about a nonfiction tome? Covered. The best examples of such may communicate technical information and be enjoyable at the same time. Ever read Bill Bryson, perhaps his Short History of Nearly Everything, for example? Tell me you weren’t informed and entertained at the same time.

How about a Hollywood screenplay? Covered. Clearly, the goal of the screenwriter is to produce something that would entertain, be enjoyed. However, the screenplay itself must be designed to be used, or the writer’s goal cannot be met. Included with the entertaining content (the story), the writer must convey all the information and instructions that the actors, directors, producers, etc. need to accomplish the goal of performing the scene as he or she intended. The writer takes on a dual role, both symbiotic with each other — the story useless without the instructions, the instructions homeless without the story.

The same goes for countless other examples. Under my system, no form of writing is more or less noble than another.

So all writers of the world, stop either feeling insecure or conceited and adopt monkeyPi’s Law. The world depends on writing that is meant to be used and enjoyed.

How well do you know your fonts?

Have you a typographer’s eye? Head on over to ILT to test your skills.

I wish I could impress you with a high score, but my first attempt was an embarrassing 22 (average is 23).

A Digg for Technical Communicators

Tom Johnson of IWBW has created a social news service for Technical Communicators.

I’ve been a long-time reader of, but just last week it dawned on me that it would be really great if there were a Digg-like site for technical communication. So I decided to create one. It’s called and it’s pretty much a Digg clone, except that the entire focus is on articles related to technical communicators.

Great idea, Tom, and thanks! Everyone head on over to WriterRiver, register a witty username, & start participating.

Hmmm… now, the question remains: how do we verb-ificate WriterRiver? With, we have “digg me,” or “I dug the site.” So, with WR… do we “WR me,” or perhaps “send me down the river? (up the river?)” Any ideas?

Tech writer launches class action lawsuit against Sun Microsystems

A former technical writer for Sun Microsystems has filed a class action lawsuit against Sun, claiming that writers are unfairly assigned exempt status.

Dani Hoenemier says she worked long days as a technical writer for Sun Microsystems, sometimes spending over 60 hours a week at her computer when the company was preparing a new product release.

Sun’s technical writers may earn salaries of $100,000 a year, but they don’t get overtime pay for the extra hours, according to Hoenemier’s attorney, who is challenging the company’s practice of treating Hoenemier and about 300 other writers as exempt from state labor laws governing overtime and breaks.

Wow - a single technical writer (that the company calls “disgruntled”) managed to create this firestorm of controversy. I don’t get it. Most technology workers, including writers, are exempt (I have exempt status). It’s a fairly standard way of doing things nowadays. Everyone knows this before they sign an employment contract.

I’ve heard (through private channels) of at least one Sun employee who expressed frustration at how the lawsuit might negate a long-term effort by the writers to get themselves recognized as professionals on their own merits. I’m sure it goes without saying that this is probably a common frustration among the writers — hence why the article goes on to say:

Many of the writers don’t want to be hourly workers and have declined to cooperate with the lawsuit, Sun said in a statement. In court, Sun argued the case should not be a class action because the writers don’t have uniform duties.

Superior Court Judge Jack Komar disagreed, although he ordered Hoenemier’s attorneys to find a second employee willing to be named as a plaintiff in the case.

If the lawsuit continues, Sun could be out well over $20 million in back pay, which might just be enough to kill the company outright. And then what kind of backlash against tech writers would ensue…?


If Monty Python designed logos

“Yessir, the new logo for Her Majesty’s Office of Government Commerce is nearly complete, eh? Certainly fetching, if I do say so meself. Mmm-hm.”

“A quite fine job, Baskins. Your mum should be quite proud, you’ve - ‘allo ‘allo ‘allo… what’s this?!? What’s this all about? Baskins, did you take at look at this, you know, as they say, ‘on it’s side?’ ”

“No, sir, I ‘aven’t… what do you OH BLOODY MERCIFUL HEAVENS!!”

“Do you mean to tell me that we just spent £14,000 to develop this… this… low-go, and that you intend me to provide this to Her Majesty’s office on monetary oversight with a straight face?”

“Well, sir, it certainly conveys that the council has a grip on wasteful spending! Haugh!

“Mm. Quite right, quite right. Maybe they won’t notice.”

“Oy! Of course not! Let’s celebrate with a warm pint, shall we?”