I'm sorry

Tiger Woods has apologized for his behaviour.

I'm also sorry.

I'm sorry for all the trees that gave their lives so that user guides could live.

I'm sorry for all the dumb questions I've asked SMEs over the years, just so our users wouldn't have to call tech support with those same questions.

I'm sorry for all my widows and orphans.

I'm sorry that I can't explain what the subjunctive condition is.

I'm sorry for having a bad fonts day.

I'm sorry that I can't spell XML or pronounce the word mnemonic.

I'm sorry for all the tech writers who still use Word.

I'm sorry for abruptly telling a developer that "Error - bad - You have failed" is neither an appropriate nor meaningful error message.

I'm sorry for all my typos. They will never happen agin.

Finally, I'm sorry for all my lousy blog posts. I hope this isn't one of them. But if it is....

...I'm sorry.

Read More

Wall Street Journal - Free My Info!

Here is a link that will take you to an interesting Wall Street Journal article:
The Microsofting of Apple?

As the page indicates, if you want to read the entire article, you'll have to pay for a Wall Street Journal subscription.

Now, go here, then click on the second or third link.

The exact same URL as the first article is displayed, with the article in full.

So there you have it - one of the most prestigious financial newspapers has no clue how to create systems that maximize its finances.

It's not that the shoemaker's children go barefoot.

This shoemaker doesn't even know what the hell shoes are, or what they go on.

Read More

The Chilean Mother of All Typos

I would not want to be Gregorio Iniguez, the managing director of Chile's mint. Under his watch (if one could call it that) thousands of 50-peso coins were circulated with a spelling error.

Now, this was not some minor obscure typo. It was not in a section of smaller, secondary text.

This typo was in - wait for it - the name of the country itself.
That's right - Chile was spelled Chiie.
(Oy. That's got to hurt.)
Looks like the mint will be looking for a new poof-reader - uh, I mean proof-reader.
The irony is that these coins, which are worth about ten cents each, are now worth much more because they are so rare.
Too bad our documentation doesn't increase in value the same way.

Read More

Olympian glitches

Before an Olympics occur, there is another sporting event: the mad spectacle of various cities fighting over each other for the chance to host the Olympics. It's as though five debt-ridden people are competing to acquire even greater debts. Afterwards, there is genuine surprise over the overspent millions.

Of course most Olympics lose money. When you create miniature cities of massive structures that will most likely be used only once, debt is inevitable. If there's one event in the world that needs single-sourcing, the Olympics are it.

Still, I'm not a complete curmudgeon when it comes to The Games. I admit I enjoy watching the opening and closing ceremonies, and the Vancouver opening ceremonies did not disappoint.

Cauldron Calamities

To be sure, there were a few problems: some of the invited First Nation leaders were a bit late in arriving, one of the giant torch cauldrons failed to rise, and a hapless Wayne Gretzky took a painful ten minute ride in the rain, in a swerving vehicle, just to light another cauldron. It would have made much more sense to have a second athlete positioned right next to this second cauldron. This way, the show would simply have quickly transitioned from one lighting to the next, but I guess the producers wanted to build up momentum, and generate a few laughs in the process.

Another problem, of course, has been the weather. While it is true that Vancouver is experiencing one of its warmest winters in history, the fact is winters in general there are quite mild, making it a rather dubious choice to hold a winter game. Is it too late to redub these "the spring Olympics"?

Half full or half not?

Still, despite all these glitches, the games appear to progressing normally. It's so easy to focus on the negative, but for every one thing that goes wrong, hundreds of things go right.

This is also true in documentation. For example, think of the features many online help systems have:

• hundreds of topics explaining every concept, task, dialog box, and field
• a TOC that links to all the topics
• a powerful search function that can rank search results
• an extensive index that anticipates all the ways a user might look up a topic
• in-line glossary terms that allow the user to hover over a term and see a pop-up of its description
• hundreds of cross-references
• the ability for users to: expand or collapse the TOC, automatically synchronize an open topic with the TOC, save favourite topics, and directly submit feedback about the help
• the ability for writers to: create reusable text objects, manipulate the order and hierarchy of topics, create and manage style sheets, conditionalize text and create variables

The code that allows all of this functionality is enormously complex, and I haven't even covered spell-checkers. The fact is that modern documentation systems are open miracles.

Reviewers sometimes take these systems for granted and get upset when a glitch occurs during the review process. However, as writers, we also take our tools and technologies for granted, until glitches start occurring. Most can be resolved; some cannot, but that does not mean we throw away the entire document.

Perfect for each other

If only "perfect" Olympics were allowed to be staged, none would be.

If only "perfect" documents could be published, none would be.

There is no perfect document; perfection is only goal we can strive towards and never achieve.

But in the process, we can produce information worthy of a gold medal.

Read More

And the Oscar goes to...

The Annual Distribution of Meaningless Awards to Shallow People, a.k.a., The Oscars, is fast approaching. This non-event is as useless as a Windows 1.0 user guide. The choices are completely subjective. Many great films and performances have lost out to lesser ones. One of the best examples of this is the masterpiece Citizen Kane, considered by many the greatest film ever made, which lost to - wait for it - How Green Was My Valley.

Now, many STC chapters have awards for technical communication. Unlike the Oscars, this is a useful awards event, if for no other reason than to have one's work judged by others. Perhaps, though, to liven things up, we need to develop sexier categories:

• Best Looking Cover Page
• Best Performance by an Index in a Leading Role
• Most Graphic Use of a Graphic
• Most Outstanding TOC
• Most Consistent Use of A Comma Before the Word "And"
• Best Use of Bold and Italic Simultaneously

Of course, we'd have to develop a nickname for the trophy. How about the "Writey"?

Doubling Your Pleasure

This year, the Academy has doubled the number of nominees for best picture from five to ten. The official reason is to give less successful but presumably worthy films a chance. The unofficial reason is to boost ticket sales and film rental revenue.

This idea is as dumb as a bag of Oscars. Why stop at ten nominations? Why not have twenty? Or a hundred? Just as printing money lowers its value (something the U.S. is painfully learning), increasing the number of nominated films simply lowers the value of a nomination.

Things that are important are important because there are so few of them. The important things in documentation include:

• the important information users need to know, as highlighted in notes and warnings
• headings, including chapter and other major headings: headings 1 through 3, for example

Therefore, if you have too many of these elements in a document, you weaken the document. For example, if you have six Important notes on a page, the reader may likely ignore them all, since if everything is important, nothing is important. Better to group all these notes as bullets under one Important Considerations section.

As for headings - again, these need to be used carefully and sparingly. Too many chapter and heading divisions in a document dilute the document. You end up with a TOC containing 47 chapters, and a chapter with 37 heading 1 sections. Instead, group numerous separate smaller sections into one large section. Split a super-sized chapter into two or more chapters. Don't force your readers to wade through a sea of sections. Combine, converge, and conquer.

By doing these things, you'll create documentation that people can actually use. This is so much more valuable than a 13.5" statue of a bald naked guy.

Read More

Recalling all recalls

"Oh, what a feeling to drive Toyota!"

This catchy jingle from a few years ago rings ironically in my ears. With all the current recalls from Toyota, this jingle needs a rewrite:

"Oh, what a feeling - to drive Toyota - into a brick wall..."

Last year, I came dangerously close to owning a dangerous Toyota. The dealer and I had agreed on a price for a new Camry. However, he was unable to actually obtain the car - apparently they had sold out, and only next year's model was available.

I never quite understood how next year's model could be available in the spring of the previous year. It's as though they've sent a car from the future back in time eight months to our present. Back to the future, baby.

In any case, they say "be careful what you wish for", and am I glad my wish for a new Camry never materialized. I bought a used Accord instead for about half the price. It also has the added feature of an accelerator pedal that actually springs back up when you take your foot off it.

Usability - A Sticky Situation

To be fair to Toyota, this is also a usability issue. Don't drivers know that if the accelerator pedal sticks, they can:

1. Press the brake pedal
and/or
2. Turn off the engine?

This may not stop the car immediately, but it sure beats the status quo. Toyota should include these handy tips in their car manuals.

Total Doc Recall

You don't often hear about companies issuing a "documentation recall". It's a mathematical fact that many documents have errors or omissions, and could be improved. Even though documents are, unlike cars, quite easy to update, most companies don't bother.

The problem is that documentation is traditionally packaged with the product and never (or rarely) updated. This is especially true of PDF files included with a product. They're written once and may only be updated when a new version of the product is released. All of the changes and improvements that were made in later PDFs, changes that could apply to earlier versions, are rarely made to these earlier versions, because it's simply too much work to retroactively update all the documentation.

Reduce, Reuse, Recycle

The solution is to recognize that documentation exists in a very different way than a physical thing like a car. Its ethereal, non-physical state liberates it and exempts it from the pitfalls of tedious physical recalls.

All information can and should be stored as reusable elements, and then regularly and automatically published as online documents. Any part of a document that applies to more than one version of a guide is stored as a single documentation element. When this element is changed, all the versions of the relevant guides are also changed, and the users will see these changes when they view the manuals online.

The concept of a "recall", therefore, simply doesn't exist in this documentation scenario, because the product is never finished.

The president of Toyota recently apologized for all his company's troubles. Maintaining an online content management system means never having to say you're sorry.

Read More

Colour my worries away...

I love the simplicity of the Homeland Security colour-coded advisory system.

This system, which purports to indicate the threat of a terrorist attack, and thereby tells the general public how much they need to worry, is as follows:

• Green - Low
• Blue - Guarded
• Yellow - Elevated
• Orange - High
• Red - Severe

(I didn't list Yellow in its colour because the lack of contrast makes it hard to read - I learned that in college.)

Rephrasing this in practical terms (which is what information developers do), we get:

• Green - Relax! Take a load off. No worries here.
• Blue - Start getting a little anxious.
• Yellow - Be afraid. Be very afraid.
• Orange - Begin making your final arrangements.
• Red - Stop reading this - you're most likely dead already.

This list could be simplified to the last three colors (yellow, orange and red), because it is doubtful the U.S. government will ever set the level to Green or Blue. This helps keep everyone in a general state of panic.

We need a similar warning system for all public, distributed information. It would be as follows:

• Green - This document is 100% complete and accurate. And it's also fun to read!
• Blue - Unless this document is describing something that could hurt or maim you, you can safely refer to it.
• Yellow - This document contains quite a few errors and omissions that we just couldn't bother fixing. Sorry about that. Proceed with caution.
• Orange - Oh boy - this document has alot of problems. Missing procedures and overviews. Tasks that you can't complete. A rotten index. I would stay away if I were you.
• Red - Don't even bother reading this. Ask your tech friend for help.

As an example, this entire blog could be classified as bluish-green.

Read More