Too many notes

The spectacular 1984 film Amadeus about the life, music and madness of Mozart includes an amusing exchange between the Austrian Emperor Joseph II and Mozart. The Emperor, having just heard Mozart's opera, gives the following feedback:

"Your work is ingenious. It's quality work. And there are simply too many notes, that's all. Just cut a few and it will be perfect."

To which Mozart replies: "Which few did you have in mind, Majesty?"

The organizers of an electoral recall in British Columbia have run into a similar problem with a document. Elections Canada has rejected the application because it contains too many words.

Or does it? Chief electoral officer Craig James turned down the application because he felt that the acronyms MLA and HST are not two words, but eight. If you replace these acronyms with the words they represent (member of the legislative assembly, and harmonized sales tax) the 200-word maximum is then exceeded.

This is a documentation limitation that only a mindless bureaucrat could come up with. Even if you do count an acronym as more than one word (an obviously ridiculous standard), why would the maximum number of words in an application of this importance be set as low as 200? Surely one page (or about 450 words) would be a more reasonable limit?

In the meantime, the petition organizers need to find a good editor and give the following instructions:

"Note: There are too many notes in our note."

Read More

The Mother of all Confirmation Messages

Most technical communicators who work in software will, at some point, be asked to write (or re-write) error and confirmation messages. This is often a very challenging but engaging activity. You have to consider the state of mind of the user who may be annoyed, upset or confused at seeing such a message. A well-written message, therefore, puts the user's mind at ease by explaining exactly what the problem is and how to resolve it.

Some examples of poorly written and well-written messages help illustrate this:

Poorly-written: Printing device out of media. (Error 34)

Well-written: Your printer is out of paper. Please add paper to the lower tray.

* * *

Poorly-written: Data type mismatch in field 23 - invalid alpha/digit entry. Message class AB43. [INTERNAL NOTE - TELL CUSTOMER HE SHOULD NOT BE SO *$*&%$ing STUPID!!! Homer Smith, Developer A41, Sector 7G]

Well-written message: You have entered numbers into the First Name field: please enter letters only.

* * *

Poorly-written: Illegal access attempt - type A342. DO NOT OVER-NEGATE  SUB-CONNECTION. MESSAGE TYPE - DFYWKJ3940983- FAILURE OVERRIDE. Please refer to subtype 5908DM4M67M4454 when quoting this message to your CIO-DM4 manager. (Form 12 is required, of course!) Have a day.

Well-written: You do not have permission to access the record. Please contact the Help desk.

You get the idea...

Recently, Google developed a message for anyone trying to import their Google Gmail contacts into Facebook. Google wanted to warn the user that they cannot export their contact information out of Facebook.

Here is the actual message users will see: (trust me, I am not making this up)

Hold on a second. Are you super sure you want to import your contact information for your friends into a service that won’t let you get it out?

Here’s the not-so-fine print. You have been directed to this page from a site that doesn’t allow you to re-export your data to other services, essentially locking up your contact data about your friends. So once you import your data there, you won’t be able to get it out. We think this is an important thing for you to know before you import your data there. Although we strongly disagree with this data protectionism, the choice is yours. Because, after all, you should have control over your data.

Of course, you are always free to download your contacts using the export feature in Google Contacts.

This public service announcement is brought to you on behalf of your friends in Google Contacts.

__I want to be able to export my data from Facebook. Please register a complaint on my behalf over data protectionism. (Google will not pass on your name or email address.)

__I still want to proceed with exporting this data. I recognize that I won’t be able to export it back out.

[Select one or more options.] [Cancel and go back]

Oh. My. God. Could Google have used more words? This is a terrible message which sends a terrible message. Because of the obvious conflict-of-interest, Google is doing everything it can to scare the user into not proceeding.

It is also ridiculous (not to mention very confusing) to have one of the options be to "register a complaint on my behalf", which is totally irrelevant to what the user's intention was. It would be like a Print dialog with the following options:

[Print the document]

[Do not print the document. I do not want to wilfully participate in the destruction of trees. Please automatically email all my contacts to let them know how much I love this planet.]

Even if you think Google should offer some sort of warning, it could have been done much simpler, like this:

Export my Gmail contact information into Facebook? (Note that you cannot export your contact information out of Facebook.)

[Yes] [No]

Software messages must be non-political, non-religious and uncontroversial.

I am "super sure" of that.

Read More

The Medium is The Messenger

Kudos to Kik Messenger, a new messaging app for smartphones, with a twist. It tells the user when a message has been sent, delivered, read, and even when the other user is responding. In doing so, it converts regular text messaging into real-time conversations.

It runs on all types of smartphones: Blackberry, iPhone, iPad and Android.

And it's free.

(No - I have not been paid by Kik to say this - I own a dumbphone, not a smartphone.)

The technology behind this app is not new: it's similar to Blackberry's messaging software. However, not everyone owns a Blackberry - something Kik's creators realized and took advantage of.

These new messaging apps are excellent examples of what I call meta-info apps. Meta-info is information about information. Sending a piece of information (such as a text) is one thing; getting information about that information's delivery, reception, content and response is quite another. It adds a whole new layer of complexity and value to the original information.

In this case, the original information we are dealing with is quite simple: a text message. But what would happen if you applied meta-info technology to a user guide?

The result could be an online user guide with meta-info that could be visible to the author or the public such as:

• the number of people who have read (or are currently reading) a particular topic
• the search terms the user entered to find a topic
• how much time the user spends reading a topic
• a ranking of the quality of a topic; that is, whether the topic was useful
• notes or comments from readers about a topic
• an overall rating of the entire guide and its ranking compared to other guides 

Can you even begin to imagine how valuable this information would be in helping to improve the contents of the guide?

Some of this feedback technology exists today, but most guides are still in the old flat, one-way format. A document is delivered to the user, and it's the last we see or hear of it. Documents using meta-info, or meta-documentation take information to the next level.

Meta-info is here to stay. Kik Messenger has been downloaded over two million times in the past three weeks.

How many users have "downloaded" your documents? The fact that most of us cannot answer this question raises many more questions.

Read More

Jay Leno's User Guides

Avid car collector Jay Leno has written a hilarious piece on car user manuals, observing how much they, and their readers, have changed over the years.

Earlier guides assumed the user actually knew how cars worked and could easily service them themselves. Today's guides assume (correctly) that the user knows next to nothing, except perhaps where to put the gas in.

Here are some of Leno's funnier examples:

A. Old guide: Removing the Cylinder Head: Obtain a block of wood approximately the size of the combustion chamber and place this under the valve heads on the number one cylinder. Press down on the valve collars and extract the split collars. Remove collars, valve springs and spring seats. Repeat for the remaining five cylinders. Valves are numbered and must be replaced in original location. Number one cylinder being at the rear, that is, the flywheel end.

New guide: Changing the battery: Battery disconnection, removal or replacement should only be carried out by qualified personnel. Consult your dealer.

B. Old guide: In the event you need to remove the engine, gearbox and clutch, in the event it is necessary to carry out a repair of all the above units, notice that the gearbox may be removed from the engine when the floorboards have been removed and the rear of the engine has been supported. Removal of the gearbox will give access to the clutch.

New guide: If engine warning light goes on, consult your dealer. 

C. Old guide: To raise the headlamp beam, rotate spring-loaded screw on top of lamp clockwise. To lower beam, turn counter-clockwise. To adjust headlamp beam left or right, slacken the two hexagon-headed screws, one on each side of reflector rib assembly, and move the reflector assembly to the desired position. 

New guide: Do not attempt to adjust headlights. See your dealer.

Some other notes from old guides include:

• An explanation of the correct "ignition point settings", showing how to "adjust the distributor and vacuum brake". The guide states: Your Ford dealer can make this adjustment for you, but there's no reason you can't do it yourself. Right, and while your at it, you can be servicing your washer and drier.

• A guide for an old car made partly of wood states: If flames start licking over the front of the hood, shut off fuel and increase speed until flames blow out. Yikes - talk about a "hot rod".
  

• This one is simple and to the point: After 1,000 miles, disassemble engine, check everything, reassemble. Got it!

All this shows there's only two things that affect the content of a guide:

• the product being document
• the user reading the document

They just don't make users like they used too...

Read More

Black Box In The Cloud

A black box is any device or system that receives input, processes it, and produces output, in a way that is mysterious and incomprehensible to the user. The user does not know how it works, just that it works.

A black box can be summed up as:

Input -> [Black box] - > Output

Examples of black boxes abound: cars, TVs, cell phones, home appliances, computers, and so on. We don't know exactly how these things work, but simply take it for granted that they do.

Now, from the perspective of our employees and clients, a technical communicator is a black box, as follows:

• Input: specification sheets, old documents, product reviews, emails, notes, assorted conversations, tall tales, rumours and innuendos 
• Black box: the thoughts and actions of the technical communicator, and the tools used 
• Output: technical documentation

A more common black box is the one on an aircraft. It is called, appropriately enough, a black box, although it is actually yellow to make it easier to find.

An aircraft's black box records its critical flight data, so that if the aircraft crashes, there's a record of events leading up to the crash. If the black box can be found, it can help crash investigators determine the cause of the accident.

The main flaw of this design is that someone actually has to find the black box. If there's no black box, you'll just have a black hole of data.

A Canadian company named Star Navigation Systems Group has developed a remarkable solution: a new black box. Instead of storing data within the box, the data is transmitted via satellite to a monitoring station.

It no longer matters if the black box is lost or destroyed, because the data is already "on the ground". More importantly, if there's a problem on the plane, an text alert is automatically sent to the appropriate people. This could be a life-saving alert, as it could allow technicians to solve a mechanical problem before it becomes a full-blown disaster.

Viraf Kapadia, the chief executive of Star Navigation Systems, explains it well:

"Say you're the vice-president of engineering for Air Canada and you're at an aviation show or conference. Something goes wrong with one of your aircraft of high priority, then you will receive an email on your computer with WiFi or your BlackBerry telling you exactly what is wrong in plain English.

"It is reactive versus proactive. The Black Box is very important when a plane goes down or a plane has had a problem and they want to do a postflight analysis, but that is always going to be after the fact. Our box is there watching in real time all the time so if there is an issue that needs to be addressed it can be immediately as opposed to t-minus one second which is then boom and crash."

To sum up: the two important things which distinguish the new black box from the old are:

• the location of the information - the information is stored separately from the aircraft, instead of inside the aircraft
• the timeliness of the information - the information is transmitted and reviewed in real time, as instead of after the fact

Traditional documentation suffers the same two drawbacks of the old black box: its location and timeliness. Most documentation is stored locally on the writer's computer. The writer can only review and update their documentation if they are physically at their computer.

In addition, most documentation is only updated when the product itself is updated and redistributed. Any important changes to a guide have to wait until the next release.

By contrast, a web-based content management system that regularly and automatically publishes its content online does not have these limitations. A writer simply logs in securely to the system no matter where they are located or even what computer they are using. Changes can be made anywhere and anytime. Content is regularly and automatically updated on a website that users can also access anywhere.

The end result is like the new black box: a system that can be accessed anywhere, and which distributes data immediately (or almost immediately).

Examples of these new information systems include web-based website and document management systems, such a Google Sites and Google Docs. However, any web-based tool that allows you to create, view, edit and manage information would qualify, including Twitter, Facebook, LinkedIn, and, of course, blogs. In fact, I have already updated this blog entry after posting it.

The old black box was in the clouds, literally.

The new black box, and, it is hoped, all important information, is no longer in the clouds, but on The Cloud.

Read More

You Lift Me Up

The Marriott Marquis is one of the busiest hotels in New York, but it had a big problem. With so many visitors and guests, the wait for an elevator was painfully long.

To add more elevators would have been very expensive and messy, because the building itself would have to be ripped apart. So instead of adding elevators, Marriot made their elevators more intelligent by implementing a new elevator control system called destination dispatch.

Under this new system, instead of choosing your floor in the elevator, you enter your floor number outside the elevator using a keypad located in the elevator lobby. The display on the keypad then tells you which elevator to board, for example, Elevator A. As you step into the clearly labeled elevator, your destination floor number is displayed near the elevator to confirm your floor. You simply enter the elevator (which no longer needs its own floor buttons) and travel to your floor.

Before this system was introduced, the elevator control system did not know where people were going until after they boarded the elevator. Now, when passengers enter their floor number on the keypad before they board, the system uses totally different formulas to control which elevator should be used.

The system takes the information from each of the waiting passengers, and groups people together who are going to common destinations on the same car, minimizing the number of stops. This has reduced elevator travel times, and improved the capacity of the system by 30%.

The only downside to this system is that some people may feel they are losing control, because they are unable to select their floor once they have boarded the elevator. However, like with any new technology, it can take some getting used to, and the benefit of a faster ride clearly outweighs any old habits.

Destination dispatch is a marvelous example of using creative thinking to an age-old problem. However, it's more than that - it's actually an application of a basic information development principle to the physical world.

Before a user reaches their "final destination" in a document (the specific topic they are looking for), they will usually have been directed to it in one of three ways:

• using a search function
• using an index
• using a table of contents

Each of these methods correspond to the destination keypad of the elevator system. The reader first enters or looks up where they want to go (the specific topic), and then actually go to that topic by following the resulting link.

A reader arriving at an incorrect topic is like the elevator user who enters an incorrect floor on the keypad. However, in the case of the keypad, it is user error. With the document, it is more likely the author's error.

This is why it is absolutely critical that the indices and tables of contents you develop are explicitly clear, otherwise they will send users to the wrong topics.

Who knew indices and tables of contents could be such a ride?

Read More