A Tech Writer's World

A Transcendent Man

2011-12-22T14:51:00.001-05:00

If I could meet any person alive today, it would undoubtedly be Raymond Kurzweil. One of the most brilliant thinkers on the planet, he is a distinguished scientist, inventor, author and futurist.

His inventions include:

optical character recognition (OCR)
text-to-speech synthesis
speech recognition technology
sampling musical keyboards

If that weren't enough, Kurzweil accurately predicted:

the collapse of the Soviet Union
the defeat of the best human chess player by a computer
the rapid growth of the Internet, and its move to a wireless format
the increase in popularity of cell phones, and their shrinking size
the move of documentation from paper form to computers and the Internet
the ability to add sound, animations, and video to documentation

Because of his track record, Kurzweil's other predictions are worth paying attention to. They are based on the Law of Accelerating Returns. This law stems from Moore's Law stating that the number of transistors on a microchip doubles about every two years. As a result, computing power is increasing exponentially and will have an enormous impact on science, including nanotechnology and biotechnology. He predicts it will be only a few decades before some astounding achievements are made, including:

the "source code" of DNA will be hacked, enabling human life to be extended using nanobots: small programmable robots that repair the human body at the molecular level; whenever we need to heal ourselves, we simply download the latest update into our bodies
a computer that fully simulates the complexity of the human brain, allowing a person's mind to be uploaded to a machine, thereby achieving immortality
artificial intelligence systems that make moral decisions and interact fully with humans
the ability to send and receive physical objects electronically

Looking further into the future, Kurzweil predicts:

The line between people and machines will blur as machines become more human and humans add more technology to their bodies.
Machines will grow to be billions of times more intelligent than they currently are.
Machines will eventually become smarter than people in a history-shattering event called The Singularity.
Human-machine hybrids will create giant supercomputers from asteroids, planets, stars and whatever other matter they can get their hands on (if they still have hands).
Computers the size of planets will be built; Earth itself will be transformed into a giant computer.
The entire universe will eventually evolve into a new life form: a massive super-computer, transforming matter and energy into a giant thinking machine.

Kurzweil explores this vision of the future in the documentary Transcendent Man. When asked if god exists, he sublimely says,"Not yet." However, I would say that the Singularity has already arrived; well, at least a portion of it has.

Writers are instructed to write what they know. This applies especially to technical writers. If we don't know what we're writing about, the result is a document where the reader doesn't know what we're saying.

Beyond writing what we know, we write what we are. We create documentation based on how we perceive it would be best understood. Because everyone's perceptions are different, no two writers use the exact same text to describe the same thing. All writing is a reflection of the writer.

If we write what we are, then we are what we write. Our writing needs to be clear, logical, organized and methodical; so do we. But if we are what we write, then what are we?

We are, or at least are connected to, the very documentation that we create. All the material that we have ever written, whether personal or professional, is a part of us, and we are a part of it. The merging of people and machines has already occurred: it is called documentation. It is the product of a human mind in electronic form. We live forever through our writings, as long as there is a computer to host them.

We have seen our documentation, and it is us. But will there ever be a time where technical communicators are no longer needed?

Not yet...

A Relatively Unique Document

2011-12-03T14:01:00.001-05:00

(Part One of Two)

It's quite amazing when a theory that's over than a century old continues to make the news.

European scientists claimed to have discovered subatomic particles (neutrinos) that can travel faster than light. If it's true, it would contradict a major portion of Einstein's 1905 theory of special relativity, which states that nothing can travel faster than light. Other scientists are therefore claiming that this new discovery must be wrong.

Now I'm no scientist, but saying that something is wrong because it contradicts the current model is not science. All science is built on updating the science before it. Rules are meant to be broken in order to form new rules, because science is a draft that is never completed.

For now, though, Einstein's theory of relativity remains an excellent model of the universe. It's a complex and often very technical theory. Fortunately, I belong to a field which strives to make the technical easy to understand.

Because relativity is so vast, this article will examine it in two parts. Part one will explore motion, gravity, and light. Part two will examine mass, energy, space, and time.

Ride the relative rocket

Have you ever been on a subway train, looked out the window to see the train across from you moving, only to realize later that it was your train that was moving and that the other train was still, or possibly vice versa?

This illusion provides a glimpse into one of the first laws of relativity which states that all motion is relative; that there is no such thing as absolute motion.

We perceive that the Earth is motionless, but in fact it rotates at about 1,700 km per hour. In addition, the earth is part of the solar system, which in turn is part of a galaxy, which is a part of the grand universe.

All of these vast areas of space move in different directions. We can't sense the movement because we're moving right along with it. It is therefore impossible to tell if something is not moving, that is, if it is in an absolute state of rest. It is only when we are separated from the thing in motion that we can actually see the motion. From our perspective, we are still and everything moves around us, or we're moving and everything else is still. Motion is relative to the perspective of the observer.

Users move through information at different rates and in different ways. Some users quickly skim through a guide, rapidly jumping from topic to topic. Others move more deliberately, carefully studying each new concept or task.

Each user believes they are moving at a "normal" speed. A slower user observing a faster one would judge the faster to be moving too fast. Conversely, the faster user would observe the slower as moving too slowly.

Both users would be wrong because there is no absolute standard for the rate of informational motion ("infomotion") through a document. Infomotion (the rate at which a user moves through and consumes information) is relative to the perspective of the user.

Gravity: You move me

Another principle of relativity states that gravity is the same as acceleration. You can begin to understand this if you take a ride up in an elevator. As the elevator accelerates towards the top floor, you feel heavier.

Astronauts experience this effect much more dramatically when they blast off into space. The force of the rocket accelerating upwards creates a g-force effect, pushing the astronauts down into their seats. Their weight temporarily increases, as acceleration mimics the force of gravity.

There's actually a formula for equating acceleration to gravity: it is 32ft².This represents an increase of 32 feet per second, each second.

For example, if you were floating out in space, and stepped into a special elevator that accelerated upwards 32 feet the first second, then 64 feet the next second, then 96 feet the next second and so on, this would mimic the effect of gravity. Gravity, therefore, is a naturally occurring (and much more convenient way) of ensuring that we don't all fall off the Earth.

There are different ways users can learn how to use or understand something. They can learn it naturally by using the product. Alternatively, they can employ "accelerating learning" through formal training or documentation.

Learning through documentation may not seem as natural as learning by using the product itself. However, a good technical communicator will it make appear as natural, and as effortless, as gravity itself.

But officer, I was only going 299,000 km a second...

According to relativity, nothing can go faster than light, which travels at about 300,000 km per second (km/s). This is the natural speed limit for all matter in the universe, and is represented in physics by the letter c.

Much information today is stored, submitted and consumed in an online format. Because information is stored electronically, it does, quite literally, travel near the speed of light. Therefore, the speed limit for light is also the speed limit for the transmission and updating of information.

However, from the user's perspective, it doesn't really matter how quickly information is transmitted because users perceive it as instantaneous. The much more relevant speed is that which the user can find and understand the information they need. We can call this the Communication Velocity, and can also represent it with the letter c. To distinguish this from the other c, we'll label it Cv.

We can calculate Communication Velocity as:
the number of relevant concepts (Nrc) understood by the reader divided by a specific time period

or:
Cv = Nrc / T

The objective of the technical communicator is to make Cv as large a number as possible. To do this, you must ensure the end user can easily to locate and understand the topics they require in as short a time period as possible. Recognize however, that just like the speed of light, there is a limit. What that limit is is a product of your skills and the level of your end user.

Got a light? Absolutely.
Imagine that you can throw a ball at a speed of 10 km/h. You get into a car moving at 50 km/h and throw the ball forward. How fast would the ball travel relative to an stationary observer on the ground? We'd simply add the two velocities together (10 + 50) to calculate that the ball would be traveling 60 km/h.

Now imagine that you're on a rocket traveling 100,000 km per second (km/s). You shine a beam of light forward. Knowing that light travels 300,00 km/s, you would think that an observer measuring the light beam would again simply add the velocities together and calculate that the speed of your light beam was 100,000 + 300,000 = 400,000 km/s.

But you would be wrong.

The observer would measure that your light beam was travelling 300,000 km/s. In fact, they would get the same result no matter how quickly or in which direction you or the observer were traveling. The result would always be the same: 300,000 km/s. The speed of light is absolute, regardless of the speed of the observer and the light source.

There are two absolute "speed limits" in information development:

the speed at which an effective document can be created
the speed at which a document can be fully comprehended

Now, it's always possible to increase the speed (that is, reduce the time) to develop a document. But the document will suffer, and will no longer be effective. The absolute minimum time required to develop a document varies, but that minimum time does exist.

The same is true for our end users. A user can rush through a document, but then they will not understand it well enough to use the product effectively. For each user, and each document, there is absolute minimum amount of time required for a user to understand that document.

Read part two

Another Relatively Unique Document

2011-11-25T16:09:00.001-05:00

Welcome to relativity, part two.

In part one, we looked at relativity's laws regarding motion, gravity, and light. Part two will explore the connections between mass, energy, space, and time.

It's all about ME (Mass and Energy)

Everyone knows e=mc², Einstein's famous equation uniting mass and energy. This formula indicates that a small amount of mass contains a tremendous amount of energy.

Atomic weapons graphically illustrate this: a small amount of unstable, radioactive material is forced to rapidly decay releasing a huge amount of energy in a massive explosion. Nuclear power plants do this on a kinder, gentler scale, but the principle is the same: mass contains energy.

To state it another way: mass (or matter) is solidified energy. These are the two states of existence for everything in the universe.

Information development also consists of two states: (subject) matter and energy. Energy is comprised of the effort required to develop information, including: researching, interviewing, analyzing, testing, writing, editing, updating and managing. All this energy is then channelled to produce a piece of subject matter.

It can take a tremendous amount of informational development energy to produce even a small amount of information. The end user never sees the energy that goes into producing a guide. But technical communicators do, and that's really what matters.

Time for some space

Relativity states that space and time exist together in a single frame of reference known as the space-time continuum, or simply spacetime. Spacetime is made up of the three dimensions of space, and a fourth dimension of time. Einstein showed that extremely massive objects can bend not only space, but also time, showing that the two are inextricably linked.

All informational objects occupy a point in space, the space being the medium the object resides in: a printed page, a PDF, a website, and so on. But these objects also reside in time: when a user closes a book or turns off or away from the computer displaying the information, the object ceases to exist, if only temporarily.

A guide itself requires space to be usable, specifically, white space. White space allows the information to breathe, improving usability. Documentation also requires time for an information developer to create and update the drafts. In fact, the highest quality drafts result when enough time passes between reviews. This extra time gives the information developer and reviewers a fresh perspective. It is a necessary space of time - a spacetime.

Be small. Slow down. That's heavy, man.

If we could observe an object traveling near the speed of light, we'd see three incredible things happen:

the object would shrink in size in the direction it was moving
the mass of the object would increase
time would slow down for the object

On the last point, if the object was a clock, we'd see it moving more slowly as time passed at a slower rate. However, from the perspective of the object, time would be passing at a normal rate. This effect is known as time dilation.

To illustrate the power of this, imagine if you were traveling near the speed of light and looked back on Earth using a powerful telescope. You'd see everything moving more rapidly on Earth, as though it was on fast-forward. You might later return having only experience a few days passing from your perspective, but returning to an Earth where hundreds, or even thousands of years have passed - a one-way time trip into the future.

These three remarkable transformations have been confirmed by science. They also explain why relativity states that nothing can travel faster than light. If an object could travel the speed of light, it would shrink to nothing, time would stop completely for it, and its mass would be infinite. To accelerate something to the speed of light requires an infinite amount of energy, which the universe simply does not have.

The incredible shrinking communicator
As an informational object is developed, it moves through the information development process. It starts out large in size and scope, consisting of many internal notes, documents, functional and design specifications, emails, phone calls, interviews and other meetings.

As the object accelerates through the process, much of the excess information is edited away. The information object shrinks in the direction of its motion, arriving at its final form: practical, relevant, and smaller.

Massive changes
Information mass does not refer to the size of information. Although we can speak about "massive" amounts of information, this does not describe the quality or usability of the information. A massive amount of information is often unusable because the user cannot find what they are looking for.

Instead, mass refers to the substance, practicality and meaning of an information object. The greater the mass, the more valuable the object is to the end user.

Again, as an information object moves through the development process, its mass increases, even though its size decreases. In fact, it is precisely because its size has shrunk that its mass (informational value) has increased, because all the non-relevant pieces have been vaporized.

Slow down, you move too fast
The slowing down of time does not apply directly to information objects, because these objects cannot experience time - only people can. Therefore, the time dilation effect applies to the people involved in the documentation process, primarily the technical communicators.

When a technical communicator moves an object through the information development process, they are intently focused on the development of its content. The communicator's perception of time changes. Were we to observe the communicator, they might even appear motionless, as though time had stopped or slowed down for them. However, from the perspective of the communicator, time progresses normally. It is only when they stop moving through the process (when they take a break) that they realize that many hours may have passed.

The end user experiences a similar distortion of time when they are so focused on reading a topic that they also lose track of time. However, the effect is not as pronounced, because it requires much more energy to create information that to consume it. When we create information, we imagine all the paths it might take, and will often experiment with different wordings and formats. The end user only sees the one final, simple path.

Who broke my Time Machine?!

Returning now to the original discovery of particles that can travel faster than light: one of the reasons scientists are skeptical about this claim is that if such particles existed, they would travel backwards in time. These types of particles have already been imagined and are called tachyons.

Backwards time travel leads to all sorts of strange paradoxes. The classic one involves going back and time and killing one of your parents before you were born. If your parent is dead, then how were you able to be born and go back to kill one of your parents?

Technical communicators face a similar paradox with their end users. Users are constantly looking for information. However, often users don't know what they are looking for. But then if they don't know what they are looking for, how will they know what to look for?

The solution involves not tachyons but taxonomy, the art and science of classifying information into a format that a user can understand and access. This means:

giving topics clear, self-descriptive names
creating a TOC that groups topics into a logical hierarchy

and, most importantly,

creating an index that can read the mind of the end user by imaging all the ways they might look up a topic

Proper informational taxonomy eliminates the docs paradox.

My Crazy Relatives
It's not surprising that documentation has much in common with the theory of relatively. All documentation is relative, because each user brings to each document their own perspective, knowledge, experience and bias. No two users see the same document the same way. Each document, therefore, appears differently relative to each user.

As we've seen, it's impossible for almost anything to travel anywhere near the speed of light, including our users. But with clear documentation, we can enable our users to see the light.

In doing so, our users will travel, not at the speed of light, but the speed of enlightenment.

A Technical Communication Occupation

2011-11-23T18:31:00.001-05:00

The Occupy Movement hurtles towards its expected demise. With the Occupiers (a.k.a. urban campers) now evicted from their various parks, this movement is headed the way of the hippies. As New York City mayor Bloomberg eloquently stated: “Protesters have had two months to occupy the park with tents and sleeping bags. Now they will have to occupy the space with the power of their arguments.” What they shall they do to occupy their time?

Has the Occupy movement had any effect? As the Premier of China said when asked in the 1970s about the effect of the French Revolution 100 years prior: "It is too soon to tell."

Still, there's lessons to be learned from this movement for technical communicators:

Lesson #1: No leader, no way

Without a leader, a group cannot succeed. The Occupy movement prided itself on having no leader, thereby laboriously deciding everything by committee. Everyone was a leader, so no one was leading. A group with no leader has no future, because there is no one with the vision, authority and responsibility to move the group toward its goals.

That is why every documentation team must have a leader, someone who can guide, enhance and develop the group. With no leader, there is no place for the group to go but off into the various directions each communicator wants to take it. With no leader, there is no way.

Lesson #2: Pursue clarity

The Occupiers had too many demands, and the ones they had were vague, among others: a redistribution of wealth, the restructuring or elimination of capitalism, world peace, a change in the system of government, and protecting the environment. Exactly what the protestors thought each of these entailed and exactly how they were to be implemented is not clear.

Clarity is the essence of effective technical communication. If your documentation is not clear, then you are not clear. If you cannot explain to a stranger a topic you have written, then you are a stranger to clarity.

Go clear, or, like the occupiers, go home.

Lesson #3: Ask Hard Questions

When evaluating news stories such as this, we must do what technical communicators do best: ask what the real, practical effects are.

Regarding the recent evictions, there were only two possibilities before they occurred:

The occupiers would all be evicted, destroying or least severely weakening the movement. Without a physical presence, there is no mental presence. This is exactly what is happening.
The occupiers would be allowed to stay. If this had happened, then the worst thing that could have happened to the movement would have happened: the public would have become used to it. When people get use to something, they forget it, until the NBT (Next Big Thing) comes along.

Now, when evaluating the contents of the document and the document management process, we must ask the same hard questions:

Does this make sense?
What is the practical value here?
What are the logical outcomes of the various choices we can make?

When evaluating the contents of a document, we ask:

What does this contribute to others?
Is there a better way to express this?
What is missing here?
Is anyone really going to care about this?

Similar tough questions need to be asked when looking at the process by which the documentation is created, reviewed, updated and managed:

Is there a better way?
How can we manage this document more effectively?
What are our options, and what is the potential outcome of each?

Companies often fall into a trap of producing poor documents or having poor documentation processes. Their response is often: "That's how we've always done it," to which our response should be: "Well then, you have always done it wrong." Another excuse is: "That's how other groups do it," to which we respond: "Those other groups are also wrong."

To effect change, you need to have COP: Creativity, Objectivity, and Perseverance. Specifically, the only way to bring about change in a document or the documentation development process is to be (in this order):

ruthlessly objective of the current state
incredibly creative when offering the solution
mercilessly persistent in actually fixing it

About one in a hundred technical communicators have these three traits.

Are you one of the 1%?

A Note on the New Notes

2011-10-28T09:00:00.000-04:00

When not wanting to pay cash, we "put it on plastic". In Canada, plastic will soon be the only choice, as our paper bills are replaced by polymer ones.

The new polymer bills, to be rolled out over the next few years, contain a number of security features to inhibit counterfeiting. These features include clear panels, metallic images and hidden numbers that appear when the bill is held up to a light.

Because the bills are made of polymer, they will last longer than paper bills. They should also survive being accidentally washed if you forget to take them out of your pocket, giving new meaning to the term "money laundering".

The Bank of Canada (like all agencies that produce money) plays a constant cat-and-mouse game with counterfeiters. They release new versions of cash, the counterfeiters figure out how to duplicate them, and the cycle continues.

Paradoxically, government agents specializing in spotting counterfeit money don't usually study it. Instead, they intensely study real money, so that when a counterfeit bill appears, the agent can easily spot it.

Counterfeit docs exists in our profession. These may be legitimate documents included in a product, but are nonetheless forgeries because they:

contain errors
are missing critical information
are unclear or difficult to understand

Studying counterfeit documentation will not make you a better writer. It will only teach you how to be a poor one.

Studying legitimate documentation that is well-written, clear, simple, accurate and easy to understand and navigate might.

How do you like them Apples?

2011-10-27T11:22:00.001-04:00

The world recently mourned the death of Steve Jobs, founder of Apple. He has been hailed, quite rightly, as a creative genius, a brilliant and revolutionary designer, and a bold visionary who completely transformed the world of personal technology. (Full disclosure - my first computer was an Apple IIc, way back in 1985. It was also my last.)

As brilliant as Jobs was, he was also stubborn, arrogant, and an extremely demanding perfectionist who was openly abusive towards his employees. In fact, his arrogance and hubris probably killed him. He refused medical treatment for nine months, insisting on treating his cancer with diet, acupuncture, herbal remedies and a psychic. This delay most likely shortened his life.

Jobs was influenced by Buddhism, which explores the connection between mind, body, and soul. Given how cruel he could be to others, and his frequent violent rages, one could say he had a "cancer of the soul". Buddhism suggests that a disease of the soul can morph into a disease of the body. It's a medical fact that some diseases have a psychological basis. Whether this was the case for Jobs, we will never know, for he now resides in the iCloud.

(Speaking of life and death, we now know why Apple devices don't have an on-off switch. Jobs felt that an off switch represented death. It symbolized for him the terrifying prospect that we're all machines that simply "power off" at the end of our lives.)

These observations are not meant to criticize or judge, but to point out that no-one is perfect, and that there is more to a person than their technical abilities.

An Untechnical Communicator
A technical communicator may be a technical genius, like Jobs. They may have extensive experience managing a wide variety of complex documentation, thorough knowledge of all the major tools, and can speak twelve languages, human and computer. But if that person comes across as arrogant, obnoxious, highly critical of others and emotionally unintelligent, they will not succeed at job interviews. Even if they do land a job, they may have a tough time keeping it. Jobs himself was fired from Apple, and it was a long road back for him to regain control.

I've had the misfortune of knowing a few individuals like these. In the end, they either change or they go, or else every who works for them goes!

All of this means that you can win a job in an interview even if you are not the most technically qualified. The truth is that most software apps can be learned in about a week or two. The more difficult skills to acquire are non-technical:

interviewing and listening
working well with others
oral communication/public speaking
time and project management
negotiating
teaching
planning
objectivity, seeing the "big picture"
being open to criticism
handling change, conflict and stress
creativity, flexibility and adaptability

If you can show that you have these skills, and a genuine passion for the job, this will greatly increase your chances of getting it.

Research? We don't need no stinkin' research!
It's interesting to note that Apple conducted no market research - no focus groups, no interviewing, no surveys - nothing. They simply designed products that they thought were cool and useful, then unleashed them on the public.

This seems to contradict to one of the tenets of our profession: to actively design with the end user in mind based on their needs and wants. Presumably, this involves working directly with our readers and having them test our documentation to see if it's useful.

The problem is that we often don't have the resources to do this. The good news is that we don't have to, for reasons that are similar to those at Apple.

Users 'R Us
The fact is - we are users. We should have a good idea of the kinds of information our users want, and the way it should be presented.

When you need information, you want it to be clear, understandable, and easy to find and use. That is precisely what our users want.

Jobs believed it was meaningless to ask customers what they wanted because they didn't know what they wanted! This was true because the products Apple created were so different from anything that the users had previously experienced. How could users be asked about something for which they had no form of reference?

In many cases, our customers may not know exactly what information they are looking for. The example I always like to give involves the mail merge process.

That Mail Merge Thingamabob
If you were documenting the mail merge process for a novice user who had never even heard of it, you couldn't simply create a topic called Mail Merging, with a corresponding mail merging index entry. Instead, you'd need to think about all the ways a user could refer to what they want to do, and then frame the topic accordingly.

For example, you might title the topic: Creating Multiple Personalized Copies of Letters and Other Documents or Personalizing a Document that is Sent to Several People. Your index entries could include:

addressing one document to several people
copies of one document, customizing
customizing a document to be sent to several people
different names, entering on a document for several people
documents, individually addressing to several people
mailings, sending customized documents to several people
mass mailings, performing
multiple copies of a document, personalizing for each person
names, changing each on several copies of one document
personalizing one document sent to several people
sending one document to several people
single documents, changing the name on several copies of
specifying different names on several copies of one document

You should be able to develop an extensive list of index entries like this without having to ask the user first.

But take great care with each entry - because one bad Apple can ruin the whole bunch.

I Can C Clearly Now

2011-10-26T11:04:00.003-04:00

The following article contains much wisdom:
All I really need to know I learned in kindergarten.

I would this reword to:
All I really need to know about technical communication I learned from the letter C.

C is the first letter of all the important concepts, practices and other things that you'll ever need to know about our profession.

We must, of course, excel at Communication, and not just the written kind. We must be excellent visual communicators, with a firm eye for the design and layout of images, diagrams, and text. This includes a good knowledge of typography, graphics, and effective diagramming - for example, formatting screen shots so that each part is clearly identified. We must be effective and Competent informational Craftspeople, taking great Care in every word we write.

We must strive for Clarity in our work. This means being Childlike, with an endless Capacity to ask foolish questions, and thereby obtain the answers our readers Crave.

Clarity includes being Comprehensible. If our readers (or Clients) cannot understand what we've written, why did we write it? We must therefore be Customer-focused. Ideally, we should observe our readers attempting to use our documents. At a minimum, we should provide a simple way for them to directly send us their Comments and Criticisms. This involves having Compassion for our readers. They are often stressed when they reach out to our guides. Our job, therefore, is to Care about our readers and create documents that gently guide them onto the right path.

The Content we develop must be Complete and Comprehensive. A document is a puzzle, but one in which you may not know the number of pieces. Knowing that you don't know what you don't know is the first step in knowing what you need to know, you know?

At the same time, our documents must be Concise. We should use as many words as required, but no more. We can achieve this balance through the Chunking of information. For example, we can create a simple overview page that contains links to various topics, rather than listing the entire contents of all these topics on one page.

Organizing and chunking the information involves Curating, the active management of all our informational objects. A museum curator decides what pieces should be displayed, where and how; we must do the same.

As we curate our information sets, we must be Cost-Conscious. This involves effective time and project management as we juggle all our guides. It also involves Content reuse at the topic, paragraph, sentence and even word level. Common copyright information, procedures and tasks, and templates are just some of the things that should only exist in one place. This will lead to greater Consistency in all our documents.

Consistency is extremely important. You should not call the same thing by different names, nor describing different things using the same.

Our documents must be Credible (or believable). If there is an error in a document, its credibility is destroyed. Also, we must be credible. Others must believe what we say when we give our advice on content and design and trust that what we say is true - this relates to Confidence.

As you grow in your career, your confidence grows. A junior writer asks others: What should I do? A senior writer is asked by others: What should I do? The difference between the two is confidence, which comes with experience.

Confidence enables you to deal with Conflict, of which there is no shortage of in the business world. When two SMEs disagree on the contents of your document, it is a conflict that you will have to work to resolve with them.

Confidence also enables you to deal with Change. Change happens on so many levels - in people, in companies, and of course, in our documents and the way they get created. Accepting and managing this change is a critical skill to have, and requires Courage. I remember a tumultuous time when, as a result of various mergers, the company I worked for changed about every year. It was a stressful time, but also exciting, as everyone worked to manage the change.

Of all the C-skills to have, Creativity is the most important, because it encompasses all these other ideas. People who win at job interviews do so because they show how they have creatively solved documentation problems. Both your resume and in your interview should overflow with samples of your creative genius. It's great that you know FrameMaker, but so do hundreds of other people. Instead, focus on how you improved the documentation and the documentation process in a creative way.

Creativity also involves working Colloboratively with others. We tech writers are an introverted lot, a habit we need to break. No person is a cubicle. The more we interact with other writers and non-writers, the better. Have you ever stopped and asked a code developer what they do? What they like? What they think of your documents?

Practicing all these skills enhances your Career. Career management is a whole other discussion. Managing your career and network of Contacts is like tending a garden. It takes time and care, but the end results are worth it. I owe my current job to the contacts I had carefully maintained.

Now, there is one C-word that is not a skill, but a shape: Circle. The letter C is like a circle with a gap:

C

The gap is symbolic of the gap that is present in all documentation: the gap between what the reader needs to know and what is actually in the document.

Salespeople have a saying: A.B.C.: Always Be Closing. Whenever they interact with clients, their entire manner and tone assumes the sale has been made - they just need to "Close" it.

Technical communicators need to practice A.B.C. We must come full circle and close the gap. Because when it comes to us and our readers...

...we are all Connected.

reCAPTCHA'd!

2011-10-19T15:25:00.002-04:00

reCAPTCHA is an excellent example of not only solving an informational processing problem in a creative way, but in solving the original problem, also solving a much larger one.

Before you can understand reCAPTCHA, you must first understand its predecessor: CAPTCHA. CAPTCHA was created to solve the problem of automated programs (or "bots") from logging into websites and thereby generating spam in the form of emails and mass postings.

A CAPTCHA screen displays a distorted image of letters or words. A person can read the letters, but a bot cannot. The user must enter the letters correctly to gain access to the system, for example, to sign up for an email account.

This technology alone is a great example of a creative solution to a complex problem. But reCAPTCHA takes it a step further by solving an even bigger problem.

This larger problem involves an ancient form of communication - the printed page. There are tens of thousands of books and newspapers that Google is trying to convert to digital text. Scanning the publications, then using OCR (optical character recognition) to convert the scanned image to text has its limits. If the text is distorted (as it is in many of the older publications), it cannot convert the text.

How does this relate to CAPTCHA? Well, about 200 million CAPTCHAs are done by people every day. If each CAPTCHA takes ten seconds, this effort represents about 63 person years of work every day.

Wouldn't it be amazing if there was a way to put all this time to good use? That is exactly what reCAPTCHA does.

Here's how it reCAPTCHA works:

When a document is scanned, it detects a word that it cannot convert. Let's call this the "unknown word".
The reCAPTCHA process sends this unknown word as a CAPTCHA for people to deciphere.
The CAPTCHA contains not only the "unknown word", but another word which the system already knows. We'll call this the "known word".
In the CATPCHA that is created, the user is asked to read both words and enter them.
If the user solves the known word, the system assumes that their answer will be correct for the unknown word.
The system also gives the unknown word to a few other people to verify that the original answer was correct.
If enough people agree on what the unknown word is, the information is set back to the original system and the converted word is added to the document that is being digitized.
This process is repeated until all the words in the document are converted.

Can you even begin to imagine the flash of genius that occurred in the mind of the Luis von Ahn, the creator of the reCAPTCHA process?

The problem is that these type of "eureka" moments are very difficult to create. They often just happen, much like the weather. You can no more force yourself to be creative that you can force yourself to love, hate, forget something, fall asleep or go back in time.

However, you can sometimes find creative solutions if you just stop what you're doing, and ask yourself some questions, such as:

Is there a better way to present this information to the end user?
What else would a user need to know about this concept, task, or thing?
How does the user use our documents?
What changes could be made to enhance the documentation development process?

I'll give some examples of real-life creative solutions that I've encountered:

Example 1: Our help files have to be checked into a version control system. Each help project can contain hundreds of individual files, and these files are often created, deleted, moved and renamed. It would have been very cumbersome to keep track of each file that was checked in and out. The solution (from a colleague of mine) was this: instead of checking in and out the various files, a zip file of the entire help system was created and checked in instead. The installation program then decompresses this zip file. Only one file now needs to be sent and tracked in the build.

Example 2: I was working with a developer on a complex database administration application. One of the functions the user could do was rerun a query by clicking a button labeled, appropriately enough, Rerun query. The developer said the problem was that there were many different queries that the user could run, and that they needed a quick way to know which one they had run before re-running it. I asked if was possible to embed the name of the query that had just run into the button name, so that, for example, if the user had run the Last Name query, the button label would be Rerun Last Name query? I still remember the developer's eyes widening and his face lighting up as recognized the elegant beauty of this solution. "Yes," he said, "it can be done!"

Example 3: Many of our help projects share content, templates, and other settings. I wanted to develop a simple content management system that would allow all the writers to share these things across many locations. I created a master help project that contained all the common content and settings. I then linked my other help projects to this master project, so that if any of the common material changed, it would automatically be updated in the other help projects. Finally, I stored all the documentation on a version control system that could be accessed by any writer. As long as each writer has the current version of the master help project and links their other help projects to it, this will ensure the templates and content remained standard.

So don't just think "outside the box".

Ask yourself if you even need the box in the first place.

The Dynamic Blogger

2011-10-19T14:02:00.000-04:00

Some of you may have noticed the new look of this blog. It's a new Blogger feature called dynamic views.

You can now choose how this blog is displayed simply by clicking a link near the top: Classic, Flipcard, Magazine, and so on.

The results are quite spectacular - the listings are display in an animated fashion. No more boring, static text.

This new feature reflects the epitome of effective design in two ways:

to enable this feature, the author simply has to change one setting - an extremely simple act
it allows the reader to have control over the display of information

This last point cannot be emphasized enough. We laugh about the days when Henry Ford said that customers could have any colour car they wanted, as long as it was black. We then proceed to create single versions of our documents in which the user is just as unable to change the appearance as they were with the black Model T Ford.

Information can be viewed in so many places: paper, websites, PDAs, tablets, and so on. If that weren't enough, everyone has their own personal preference on how that information is displayed. The ability to give the user some control over that appearance is paramount.

Blogger's dynamic views currently has seven options. Expect to see that number rise to...infinity.

The Art of the White Night

2011-10-06T11:22:00.004-04:00

I recently experienced my first Nuit Blanche, an annual all-night outdoor contemporary art event held throughout downtown Toronto. The event featured a wide of variety of strange and exotic exhibits.

The Heart Machine consisted of four giant steel "arteries" each connected to sensors that when touched the correct way caused giant flames to shoot up, warming the frozen crowd. Flightpath Toronto, held at City Hall, showcased a spectacular outdoor laser show, while people flew overhead on a cable line.

My favourite exhibit was Soon. Held in a large, open outdoor office courtyard, it was the most spectacular work of art I had ever experienced. Searchlights mounted atop office buildings continually scanned the crowds while smoke spewed everywhere. Sounds of helicopters, along with a strange, other-wordly noise, blasted from speakers. The effect was surreal - you were trapped in a bizarre, futuristic totalitarian state.

Almost all the exhibits relied on modern technology: computers, large screen projectors, lasers, and cutting-edge sound and light systems. Without this technology, these exhibits would not be possible. Therefore, technology directly influences and is used by modern artists.

Art (non-technical) communication is therefore influenced by current technologies. Technical (non-artistic) communication is no different. User guides are written in the language of the technology of the day. We have progressed from writing on walls, to writing on paper, to printing on paper, to computers, PDAs, smart phones and beyond. However, the goal remains the same: clear and concise communication.

For both artistic and technical communication, the medium is more than the message - the message and the medium are inextricably linked and blurred beyond recognition.

This blurring occurs in other ways. One of the non-official exhibits was The Red Dot. The theme was inspired by the practice in art shows of placing a small red dot on the descriptive tags next to paintings that have sold. Various sculptures made of red dots were on display, but in addition, large red dots were affixed to various items throughout the area: buildings, trees, doors, cars, and even people. The idea was that "art is everywhere". The intent was to blur the line between art and the so-called "real world".

The effect was rather exhilarating. As my friend and I walked the streets, I began wondering what was real and what was art. At one point in the evening, I saw paramedics help out an ill person. Later, I witnessed a skirmish where several policemen forcibly held down someone resisting arrest. But were these real events, or were they staged? For a split-second, it was difficult to know. When anything can become art, art becomes anything.

Although there is an "art" to documentation, documentation is not art. However, documentation, like art, can exist anywhere. With the liberation of information through the Internet, any one can become a technical writer through blogs, feedback on corporate websites, forums and any other online area where information likes to gather.

This blog attempts to be a hybrid of both art and technical communication. My hope is that it teaches you how to be a better technical communicator, but I consider it creative (non-technical) writing. Which means it blurs the line between art and reality. Which means that any at time, I could

[Blogger server error 2352 - the remainder of this blog entry cannot be displayed*]

*or can it?

Here kitty, kitty (or maybe not)

2011-09-22T15:58:00.001-04:00

I'm not a cat lover, except for Schrödinger's cat, a mind-bending paradox proposed by Austrian physicist Erwin Schrödinger in 1935:

Imagine a cat is placed in an opaque box with a container of radioactive material and a vial of deadly poison gas. Quantum mechanics states there is exactly a 50% chance that an atom in the radioactive lump will decay and release an electron. If this happens, the electron will strike the vial, causing the gas to leak out and kill the cat.

Now, because we can't know for certain if the gas has been released, the cat exists in an uncertain state: it is both alive and dead at the same time, which is of course, impossible. But it would theoretically be true, if we could build such an experiment.

Schrödinger was trying to show the absurdity of quantum mechanics, one of the strangest areas of physics. Quantum mechanics assigns probabilities of existence to subatomic particles, leading to strange worlds where a single particle can be in two places simultaneously, or in no place.

Quantum mechanics may represent the truth at a subatomic level, but, as Schrödinger's cat shows, it becomes absurd when applied to the visible world. Instinctively, we want to believe things exist in a certain state. Even the most ardent cat-hater would rather know the cat is alive than not know either way.

The lack of certainty is at the core of this paradox. I have previously shown that a document can exist in a quantum state. That is, the state of a document can be unknown, for example:

a user may have expanded or collapsed the sections of an online help file
if there is more than one version of a document, we cannot know which version the user is reading
if the documentation system supports it, a user may have annotated certain topics - we cannot know which ones or what the user has written on them

However, what should never be uncertain is whether the user is uncertain about the contents of the document. Whatever topic the user reading, we must be sure that the user completely understands it.

How do we create such certain documentation? The same way as with any other user-friendly product: by showing it to as many users as possible and seeing if they understand it. Documentation testing creates guides that are comprehensible rather than reprehensible.

A user cannot simultaneously understand and not understand a topic. A user either comprehends your document, or they do not.

To put it succinctly: there can be no Schrödinger's User Guide.

Netflix My Net-Docs

2011-09-21T15:23:00.000-04:00

Meanwhile, in an alternate universe, the following message appeared on a website:

This site is only available for viewing next Thursday, from 2pm to 3pm. If you would like to view it after that, we can mail you a printed copy in 7 to 12 business days.

Actually, this isn't too far from reality. Do you know there are people who still:

drive to a bank to pay bills, when they could do it online?
mail printed photographs to their family, rather than email them?
manage documents as part of a group, with each group member keeping their own duplicate copy?
watch movies and TV programmes according a broadcaster's schedule?

The last point is particularly interesting. Why is it unacceptable to have a website (or any online content) that could only be viewed certain days and times, but it's acceptable to have other content that's only available certain days and times. Either scenario is ridiculous.

Through downloading, online reruns available on various broadcasting websites, and streaming services such as Netflix, gone are the days where you have to wait for a day. In addition, some of these services allow you to enter meta-data about your preferences, and to rate what you've seen, enabling the service to suggest content that might interest you. On certain sites, you can also add comments, which is pretty tricky to do using a television.

We're therefore seeing entertainment content catch up with the principles of informational content, namely:

available for viewing any time, anywhere
customizable
permanent
enabling two-way communication

I can imagine a not-too-distant future where our children and their children will look back and laugh as they cry: "You mean you guys actually drove to a store to watch a movie? And there was actually stuff that wasn't online?!"

The horror, the horror...

Shaken

2011-08-30T11:10:00.000-04:00

It's not every day that you get to experience an earthquake, and I've had the misfortune of experiencing two, both times in the building I work. The last one, with an epicenter in Virginia, shook our entire floor for several seconds.

At first I thought we were expendable employees since no one came around to evacuate our floor. It turns out that remaining in the building was the safest action, as most injuries are caused by falling debris when leaving a building. Many workers were therefore wrongly evacuated from their workplaces. People need to re-read the "disaster" chapter of their office safety guides.

Thankfully, this last earthquake caused minimal damage and no deaths, but many others have been terrible killers. The 2010 Haitian earthquake killed over 300,000 people. The world record goes to China, where an earthquake in 1556 claimed a staggering 830,000 lives.

Note that earthquakes don't actually kill people - the collapsing buildings do. This explains why there were so many deaths in Haiti, because many of the buildings were very poorly built, since Haiti itself is very poor.

Buildings simply aren't natural - they are man-made. When you combine the natural with the unnatural, you naturally run into problems. Earthquakes occurring in non-developed areas do not wreak the same level of destruction as in developed areas. Mountains and trees, being part of nature, usually remain intact.

One way to build safer buildings, therefore, is to look to nature. Just as most trees sway but don't collapse in a quake, newer buildings are designed to sway when the ground shakes. By emulating nature rather than fighting it, lives are saved.

It requires a great deal of money, time, testing and study to copy nature. This is a general principle of all design. Making the unnatural natural does not come naturally, or cheap. Software that converts spoken words to text is a good example. Great strides have been made in speech-to-text applications, but they are still not 100% correct.

A more extreme example is replacement limbs. Even today, it is difficult to create artificial limbs that have the same look and feel of the original parts. It is the supreme challenge to make the logical biological. The day may come when a replacement arm feels no different than the arm it replaces - I would give my right arm to be the inventor.

Technical communication also attempts to make the unnatural natural. It is the process of helping a person interact with something unnatural (a man-made product, service or thing) using something unnatural (a man-made document) in such a way that they can understand and use this manufactured thing in a natural way.

Therefore, the hardest things for a technical communicator to do are:

describe something using natural language in a way that a user can easily understand
encapsulate and package this information within a form that a user can use with minimal effort

Documentation should be like a glass bowl displaying only its pure contents. If the user can "see" your document, it blocks the view of the contents, frustrating the user. Similarly, if the user has to struggle to find or understand the relevant information, then the guide becomes unnatural, and is no longer a guide, but a wall.

The most well-design documents don't appear designed - they simply work in a way that does not conflict with the human user. Now, it would certainly be easier to design documentation if we were all robots, but then our jobs wouldn't be as fun, would they?

Technical communication, therefore, is the process of making the unnatural natural. A successful document is one that makes the understanding and use of a product, quite literally, "second nature".

A Lasting Theorem

2011-08-24T12:28:00.000-04:00

Here is one of the world's most difficult mathematical problems:

For the equation: aⁿ + bⁿ = cⁿ, where a, b and c are whole numbers, n must equal 2. In other words, this equation only works if n =2.

For example, the following numbers fit this equation:
3² + 4² = 5² and 5² + 12² = 13². If n equals 3 or any other number, you won't find any solutions to this equation.

This problem is known as Fermat's Last Theorem, named after the French mathematician Pierre de Fermat, who lived during the 1600s. While annotating a book about mathematics, Fermat claimed to have found a solution. He wrote: "I have discovered a truly marvelous proof of this, which this margin is too narrow to contain." Too bad he wasn't using a Word processor with its ability to add notes of unlimited size.

The problem remained unsolved for over 350 years until a British mathematician named Andrew Wiles finally conquered it in a monumental 200 page proof. How he solved it is a fascinating adventure into the strange and mysterious world of higher mathematics.

Wiles' solution involved two very strange mathematical shapes: elliptic curves and modular forms. Elliptic curves resemble doughnuts, whereas modular forms don't resemble anything and are therefore much more difficult to describe, but here goes:

A modular form is an incredibly complex, highly symmetrical form with many dimensions. It is impossible to draw one because it only exists as a conceptual form.

Elliptic curves and modular forms are very different from each other. However, the solution to the theorem involved proving that these two shapes, are, in fact, the same. When the idea that these two forms might be identical was initially proposed, it was a radical concept. It was like saying that an elephant is a banana, which is, quite simply, bananas.

However in 1995, Wiles proved these two forms were indeed identical. In doing so, he solved Fermat's Last Theorem. How proving that these two forms were the same also solves Fermat's Last Theorem is beyond the scope of this article. (For a full explanation, read the PBS transcript from the Nova documentary, The Proof.)

Mathematics and technical communication both attempt to model reality, and both use informational objects to do so. The primary object (or shape) that a technical communicator develops is the information repository, which is comprised of:

Topics (such as overviews or procedures) that answer specific questions.
Containers and sub-containers for the various topics (such as other topics, pages, chapters or other sections).
A function enabling the user to search the topics (an index, TOC, or content search function).
An environment that contains all the topics and the search function (for example, a PDF, help system, or website).

Users deal with another shape: informational queries, which are comprised of:

The generation of specific questions, such as "what is this thing?", "how do I perform this task?", "how do I resolve this problem or error?"
The process of determining where to find the answers.
Locating the relevant information repository.
Searching the information repository.
Locating the topic that they hope will answer their question.
Understanding the answer to their question, that is, the contents of the relevant topic.
Successfully resolving their question, for example, by understanding a concept, completing a task or resolving a problem or error.

Both of these shapes require all of their respective components in order to be considered complete shapes. For example, an informational query is incomplete if the user can only complete the first six steps. They may find and understand the relevant help topic, but if they cannot complete it (due to an error in the topic, the product or both), then the informational query is incomplete.

Just as elliptic curves and modular forms, two radically different shapes, were proven to be the same, both information repositories and informational queries are the same. This is because each shape is a reverse-engineered version of the other.

When a technical communicator creates an information repository, they are attempting to recreate the steps that a user will follow in an informational query. Communicators try to anticipate as many of the questions that a user will have, then work backwords to create a resposity that will the answer the user's question.

We can take the steps of an informational query, change their order (mostly by reversing them), and then structure them from the perspective of the technical communicator:

Consider all the potential questions a user could have.
Create topics that successfully resolve these questions.
Ensure the topics are written so that the user will understand them.
Index the topics so that they are searchable.
Create a search system that will enable the user to find the relevant topic.
Place the information repository in a location where the user can access it.
Make it obvious to the user where the information repository is located.

Conversely, we can reverse engineer an information repository from the user's perspective:

A user needs to:

Locate the environment containing the relevant document that will answer their question.
Search the topics for the answer.
View the various topics that might contain the answer.
Find the topic that answers the question.

One shape is but a mirror-image of the other.

The commonality goes even further, for all end users are potential communicators, and all communicators should ideally "be" the end user. The greatest documentation is created when end users actually communicate directly with the technical communicator, and when the technical communicator imagines themselves to be the end user, with all of their worries, concerns and, most of all, questions.

In fact, I have developed a formula that proves the number of end users in the world is equal to the number of technical communicators.

Unfortunately, this blog is too small too contain it.

Pizza conflicts

2011-08-18T09:30:00.001-04:00

My pizza user guides are hurting my head.

A large store-bought pizza came with not one, but two sets of cooking instructions. One set printed on a label on the front, the other printed on the cardboard back. They specify different cooking times and temperatures.

What's a hungry tech writer to do?

Using the latest information analysis techniques, I averaged out the temperate and cooking times and analyzed the result. The result was that the pizza cooked rather quickly, so it could be that the front instructions (with the lower temperature) were the more correct ones.

You'd think that the manufacturers of the cardboard backing and the manufacturers of the front label would talk to each other and issue only one set of instructions. They are probably not even aware of each other's existence.

This is a good case where is less information is more. Better to have one set of instructions than two sets that conflict with each other, a common hazard in our profession.

Dude, where's my document?

2011-08-17T11:16:00.002-04:00

Try this experiment:

Think of a printed guide you worked on.
Find the source document from your current location.
Make a minor change to the document.
Go to the locations of all the end users: their homes and offices.
Remove the previous guides.
Replace the previous guides with the new copies.
Complete steps 1 through 6 immediately.

Done yet?

Now try this:

Using your Google or Gmail account, create a Google document.
Enter some text into it.
Open another copy of your web browser, or open a different browser.
Copy and paste the URL from one browser into the other. The document will now be displayed in both browsers.
Resize the windows of both browsers so that they are displayed adjacently to each other.
Make changes to the document in one browser.

A magical thing happens: you'll see your changes in the other browser window in real time. That is, changes made in one browser instantly appear in the other as you type them.

This functionality allows multiple authors to edit a document and see each others changes as they happen. In addition, the document can be instantly published to the web, and be configured to automatically be republished when changes are made.

Compare this with the old model, where changes did not appear until the next printed release or until the revised files were uploaded to a website.

The question "where is the document?" has become as meaningless as "where is four?" Documents like these no longer exist in a single location but in every location. They have become as ubiquitous as concepts, philosophy, and gravity, not enclosed in a physical location but rather a metaphysical one.

Now some communicators proclaim: "information wants to be free". Information cannot "want' anything - it has no personality but that which we ascribe to it.

Communicators create and manage information - we control it. It is not that "information wants to be free" - it is that we can, and must, free it from its prison of physicality and non-universal accessibility.

Shared, web-based workspaces are a good place to begin the liberation.

The New Medium is the Message

2011-07-27T11:57:00.006-04:00

Marshall McLuhan

The 100th anniversary of master communicator Marshall McLuhan's birth was celebrated July 21, 2011. McLuhan was a leading expert in communication theory, his most famous saying being: "the medium is the message". But what exactly did he mean by that?

All communication requires an environment to contain it - its medium. McLuhan was saying that the specific form of a medium is actually embedded in the message that is being communicated. In doing so, there is a relationship in which the medium itself affects how the message is perceived. That is, the line between the information and the container of that information is blurred.

An example of this is a TV news story about a terrible crime. The message presented in the news story may not be so much about the crime, but more about our negative attitudes towards crime, attitudes that are influenced by the very fact we are viewing in our home the news about this crime. That is, the medium (TV) is transmitting and influencing our perceptions of crime in general. The subtle message is that crime is everywhere, even in your home, on your TV.

McLuhan was a tremendous visionary and forward-thinker because many of his ideas can be applied to modern media and technology. Information technology has changed a great deal since McLuhan's time, but his principles remain relevant.

Comparing old and new technical communication technology and processes can give us insight into the message of the new medium. The following sections list the major differences:

Documentation Formats
The type of documentation delivered.

Traditional: paper, PDF, local help files
Modern: online (websites, discussion groups, help files, blogs)

Managing Content and Form
How the the information itself (words, graphics, diagrams, and so on) and its form (its physical appearance, including formatting) are managed.

Traditional: a writer manages the information and its formatting simultaneously using a WYSIWYG editor
Modern: the information is separated from its form using an XML editor; a information developer creates and categorizes the raw data; an information architect designs the visual form the information will take; the same information can be published to different formats (PDF, online help, website, RSS feeds, tablets, smart phones and so on) using different publishing targets

Reviewing and Markup
The process reviewers follow to indicate their changes to a draft.

Traditional: reviewers mark up paper copies or send emails
Modern: reviewers mark up an electronic copy; the writer directly incorporates these changes into a working copy; multiple reviewers can review same copy simultaneously and see each other comments; a record of all comments and changes are kept, allowing the writer to revert to any previous version

Documentation Access
The degree to which the source document can be updated by the writer and viewed by the end user.

Traditional: the document can only be edited on the writer's system and can only be viewed on the end user's system
Modern: the document can be edited anywhere via a secure online server and can be viewed online anywhere

Information Currency
How current the information is; the frequency with which the document can be updated to ensure the end user is viewing the latest version

Traditional: the end user's version is only as current as the product itself; changes do not appear until the next release
Modern: the writer can update information at any time; the end user can view the changes online in real time

End User Feedback
How easily end users can comment on the documentation.

Traditional: writers review the document with the end user in person, a time-consuming and expensive process
Modern: users can rate and submit comments directly on specific topics via the web; the writer receives an email notification of the comments

The message of this new technical communication medium is that information should be free for both its creators and consumers. A writer should be able to access and update their source files anywhere. End users should be able to view the information anywhere, and know that they are viewing the latest version. They should also be able to give immediate feedback on the quality of the information. These are the obvious messages.

The deeper message is that we can all be creators and consumers of information, and that we demand much greater control, and a greater say, in the content and accessibility of this information. Information is power, and we all desire more power over this power. That is the true message.

Finally, this blog is a part of this new medium, and therefore embraces this message. I can access and update it anywhere (and frequently do.) All changes are published immediately. Using the Subscribe to: Posts link at the bottom, you can view these postings in any RSS reader. And you (the end user) are free to comment on these postings.

The medium and the message have become one.

Renaissance Man

2011-07-14T15:08:00.011-04:00

Who amongst us would not strive to be that most self-actualized of persons, master of many fields, an intellectual powerhouse, knowledge warrior and universal genius known as a Renaissance Man.

A Renaissance man (or woman) is not simply a jack (or jill) of-all-trades. It's someone who has an outstanding talents in, and great knowledge of, a wide variety of areas. Leonardo da Vinci is the classic example. He was an exceptional artist, scientist, engineer, inventor, and so much more. He was intensely curious and had a tremendous imagination: the ultimate technical communicator. Using his plans, many of his inventions were reconstructed in modern times and performed well.

Technical communicators are not just technical, and we do far more than communicate. A true technical communicator is a Renaissance communicator, as our talents involve many other professions and fields of knowledge.

Renaissance Communicators are:

artisans designing, formatting and shaping words and images, as well as sound and motion in instructional videos
teachers imparting information to others in a manner so subtle and seamless that our students don't even realize they're learning something
architects designing and building complex informational structures
physicians healing incomplete, incorrect or inaccurate documentation
detectives piecing together clues to solve the mystery of the product we document
translators and interpreters of the meaningless into the meaningful
magicians turning chaos into order and creating guides out of thin air
craftspeople building, tweaking, and endlessly tinkering with our data creations
cartologists of information mapping the big picture of a product or service
code-breakers decoding incomprehensible gobbledygook into meaningful prose
archaeologists hunting for buried informational treasures
ambassadors between those who create products and those who use them
journalists persistently pushing, prodding and probing our subject matter experts with the tough questions
soldiers in the war on error and confusion

We are the true multi-taskers, knowledge workers, and service bureaus that willingly absorb the pain of misinformation, disinformation and no information to create informational works of art.

Not only are we Renaissance Men and Women, our profession itself is undergoing a renaissance, as technical communication processes move toward separating form from content.

It's a Renaissance, man.

The Seven Lively Sins

2011-07-06T10:10:00.005-04:00

Quick quiz - can you name the seven deadly sins? And no, Dopey and Grumpy do not count.

The seven deadly sins are:

wrath
greed
gluttony
pride
lust
envy

and (my personal favourite)

sloth

I would have loved to have been on the committee that chose these sins above all others. ("If you vote for lust, I'll give you pride and sloth.") In any case, the final list is as good as any, and remains quite popular, as popular as the sins themselves, unfortunately.

An easy way to remember these sins is to use a "leggs password". Taking the first letter of each sin and rearranging them, we get LEGGSPW - or "LEGGS PassWord". Be sure to write that down.

The seven sins, one for each day of the week, were well-documented in the 1995 film, Se7en. It is one of the darkest films I've seen, both literally and figuratively. We enter a nightmare world in which an insane serial killer with a God complex murders his victims according to the seven deadly sins. The twist ending is so disturbing that to this day, I still shudder whenever I see a courier truck. (Those of you who've experienced this film will know what I mean.)

On a lighter note, they say when life gives you lemons, to make lemonade. Since I'm not a preacher, I won't attempt to dissuade you from carrying these sins into the world of tech comm. Playing "devil's advocate", these sins, if implemented constructively, can actually make you a better communicator. Rather than being deadly sins, they can be quite lively.

Let's start the sinning...

Greed
The greatest quote about greed is in the film Wall Street, when the ruthless mogul Gordon Gekko makes the following statement:

Greed, for lack of a better word, is good. Greed is right, greed works. Greed clarifies, cuts through, and captures the essence of the evolutionary spirit. Greed, in all of its forms; greed for life, for money, for love, knowledge has marked the upward surge of mankind.

"Greed for knowledge" - amen to that. Greed for knowledge, information, clarity, consistency and simplicity. If you're not greedy for these things in your work, it will burn in the hell-fire of bad documentation, and that's a real sin.

Pride
We should all take pride in our work, but not be boastful. We have to humbly and sincerely recognize we technical communicators are just like everyone else - only better. For what other species of humanity is as sensitive to words and meaning as we are? We are the patron saints of clarity, simplicity and functionality.

Gluttony
I admit I'm a glutton - not for food, but for information. I devour newspapers, magazines, books, blogs, websites, signs, posters, and even junk mail. I stuff my mind with it until it's bursting. It's alot to digest, but there are lessons to be learned (and great ideas to be stolen) from all of it, so I've no plans to diet.

Lust
When you see a beautifully designed quick start guide, a well-organized manual, a perfectly arranged help system, a clear and simple procedure, this should turn you on. If it doesn't, there's a malfunction in your informational libido, your user manual mojo, and you must see a Doc doctor immediately.

Sloth
Sloth is such a destructive sin that there's really no way it can be useful in communication. Its only value is recognizing it in others. Non-writers and lazy writers who produce bad documents are "slothful". They should anger us into action, empowering us to clean up their messes when called on to do so.

Users can also be slothful, but since they are paying our salaries, we have to be more forgiving. Design your documents so that even the laziest user can get the information they need, quickly, easily, and with minimal effort. They should be able to fly through your document as they lie on their couch, doughnut in one hand and TV remote in the other.

Envy
Envy is the honest way of stating you have a desire for change. To be a great communicator, read the works of great communicators, and ideally meet them. But don't just admire them - envy them. Then become the type of communicator that others will envy.

Wrath
It's easy to pour our wrath onto those who think they can write but cannot; on engineers who create error messages such as Error 43 - Big. You have failed.; on marketers who use strange words and phrases like actualize, customer-centric and out-of-the-box thinking; on reviewers who mark up a 400 page draft with just two words: Needs work.

How simple life would be if we could just release our fury onto these people. However, living in a somewhat civil society, we are precluded from most acts of violence. Instead, let us direct our fury, our anger, our wrath towards the documents themselves. Documents are so much easier to change than people.

So let us take these broken and bruised clumps of information, and with all our might and energy, reshape them into clear and meaningful documents.

Let there be no mercy, as we unleash in full force our technical, communicative, organizational and design skills onto our work.

Let us be...wrath.

And may God have mercy upon the soul of the document that we are about to remake in our image.

An OS is not O/S

2011-07-05T16:04:00.005-04:00

Being a person of many hats, it only made sense to buy one recently - one with a large brim to protect myself from UVA, UVB, and whatever other radioactive letters the sun wishes to hurl at me.

The hat I purchased included a tiny inline document (also known as a "tag") which simply stated O/S, a cryptic acronym indicating One Size. In other words, the hat manufacturer was too lazy and cheap to offer assorted sizes, and decided to fool the customer into thinking that size doesn't matter. The result is that for some the hat is too large, and for others, too small. The solution is to have an average-size head, however these can be difficult to obtain.

In software, the letters OS have a different meaning, of course, as the abbreviation for Operating System. Long gone are the days when there were two main platforms: Windows and Mac. There's Unix and Linux and Android (oh my!), Ubuntu, Blackberry OS, Chrome OS and many others; there's almost as many OS's as there are, well, hats.

The tremendous variety of devices each with their own OS is proof that there's no one-size-fits-all OS. That is, there is no O/S OS. Each user has their own needs and desires. Within each OS, you can customize the look, feel and functionality even further, creating a nearly infinite number of "sizes".

The funny thing is that most users neither know nor care that their devices have a so-called "operating system" - they just want to do stuff, like make calls, find information, or play a game. The fact is that most devices have some sort of operating system or they wouldn't be able to - operate. Watches (digital and analog), TVs, basic corded phones, washing machines, DVD players, cars - all these things require an operating system. When was the last time you pined for an upgrade for your clothes dryer? We don't care that a toaster has an OS - we just want toast.

So how would we define an operating system? It's not just software. As its most basic level, it is a structured environment that receives input, processes it and creates output. It can also organize and manage the things in that environment. A software OS, for example, must have file management capabilities.

Any document is an OS for information. For example, a user can interact with an online help system by searching it, resizing it, bookmarking certain topics, and if possible, annotating it and submitting feedback on it. The end product is knowledge - the document is the OS allowing this knowledge to be transmitted.

This definition of an OS can be extended as far as your imagination will take you. The gears and pedals on a bicycle are the operating system for that bicycle. They receive input (force from the biker) and transform it into energy and movement (output). Every living thing has an OS - the infinitely complex arrangement of cells, nerves, muscles, bones into a living form, all coded with DNA. Although we recognize each other through our physical appearance, we know each other through our minds and souls. The body, then, is the OS for the soul. When the hard drive of a body crashes, the soul goes with it, at least in this world.

The world is the OS for humanity, our universe the OS for this world, time and space the OS for the universe, and existence itself is the OS for God or whatever force you believe runs the universe.

So to all those wizards who continue to create OS's so magical and subtle that we don't even see them - my hat's off to you.

A few good elements

2011-07-04T15:56:00.003-04:00

The ancient Greeks believed that everything in the world was made up of four basic elements: Earth, Water, Air, and Fire. This concept was so powerful it lasted even through the Renaissance. Interestingly, the first three elements correspond directly to the three states of matter: solid, liquid, and gas. The fourth element, Fire, corresponds to energy. Given that matter and energy are the two main elements of the universe, the ancient Greeks were not far off in their view of the world.

Aside from the physical aspects of these elements, there is the meta-physical. Earth, being solid, represents stability and tangibility - that which can be touched, seen and known. Water, being liquid, represents change and movement. Air is invisible and therefore less tangible - we cannot see it directly but can see its effects. Air is also the medium required to support Fire, and life itself. Fire is pure energy that can change matter from one state to another. It can thaw ice, converting it to liquid water, then to steam, a gas.

Aspects of these four elements exist in technical communication. Earth is the visible, stable portion of a document - the portion that can be seen and which rarely changes. A printed manual is forever Earth - never changing until replaced by a newer version.

With more documentation now online, information has shifted in form from Earth to Water - ever flowing, ever changing, and increasingly customized and shaped towards the specific needs of the end user.

Air is the medium through which documentation is delivered. The printed page, the monitor, the smart phone, the tablet - the medium is not the message but is the air in which it lives. Air is also the white space around all words, text and images, allowing the words to breathe. With no medium or no white space, communication would be starved of life.

Fire is the energy that flows through the mind of a technical communicator, allowing them to shape, bend, twist and change the words and images they yield. It is the transformative power that a skilled communication craftsman uses to alter the form and substance of information. For a spectacular of Fire, see the CSS Zen Garden, where stylesheet magicians forge communicative works of art, as swordmakers used to forge metal in fiery furnaces.

Air. Fire. Earth. Water.

Note the words formed by the first letter of each element: AFEW.

All you need is "a few" elements to create a universe of communication.

Doc Men

2011-06-24T14:18:00.003-04:00

Mad Men is a highly-acclaimed and extremely addictive TV series set in an ad agency in the 1960s. This show is so popular that other networks are copying it. This fall, ABC will showcase Pan Am (think Mad Men in the sky), while NBC will air The Playboy Club (think Mad Men in Chicago). All these programmes reflect a nostalgic renaissance in the 1960s.

I was born in the 60s (1966 to be exact) so I have no memory of them. All I know is how they are represented. Growing up in the 70s and 80s, the 60s were the decade of hippies, Vietnam, flower power, Woodstock, sex, drugs, rock and roll. (Can one be nostalgic about nostalgia?) But this "groovy" world is not the one in these shows. It is the anti-hippie world of wealth, power, privilege, and sharp suits with thin ties. The only drugs on Mad Men are cigarettes and alcohol, usually in vast quantities.

We long for a certain era because we perceive it had something positive that the present does not, or that it did not have something negative that the present has. The 60s had sexism and racism, but they did not have the mad stress of today, where you can be online for work or play 24 hours a day.

The 60s had none of the political correctness which have culminated in so-called "human rights commissions", where money is given to "victims" due to hurt feelings. One of these commissions rewarded money to a patron who was offended by a comedian during a live show.

In the 60s, people and governments generally lived within their means. Today, individuals and all levels of government have massive levels of debt. In the 60s, western nations regularly intervened in other countries. Today, they are reluctant to help out as citizens in other nations are slaughtered by their leaders, lest they be labelled "imperial".

These shows, then, symbolize an era free from our repressive and culturally hyper-sensitive world. The political incorrectness of this time is encapsulated in its ads and educational films. Hilarious to watch today, they paint a picture of a simpler time, but are offensive by today's standards.

With that, I offer several fictional examples of various educational and corporate communications. Enjoy the ride back in time...

TV Ad for a Garbage Can
Introducing the new Maxo-Garbage can. It can handle any kind of waste that you can throw into it! Food waste, paper, cardboard, pop cans, glass jars, packaging - all kinds of garbage. It all gets mixed together in the amazing Maxo-Garbage can. It has easy gliding wheels to help even the smallest woman move it - nice hauling, there, Mrs. Jones! Now it's off to the garbage dump and on to the incinerator with contents delivered by Maxo!

The Canadian Immigration Agency
(A high school education film.)

The Canadian Immigration Agency helps people from all over the world to settle in Canada. Let's follow a family from India as as they make their way over to a better country.

Meet the Singh family: Abhijay, Jawahar, Utkarsh, Viraj, Saptanshu, Sushila, and Nilambari. Boy, those sure are funny sounding names, aren't they? The Singhs are on their way to Canada. We're profiling the Singhs because they were the only ones that had a last name we could pronounce.

The Singhs have arrived in Canada during the cold winter. Looks like Mrs. Singh should have packed some winter coats! They'll learn soon enough to get used to the sub-zero temperatures.

The Canadian Immigration Agency will help this family settle in. We know it can be tough for families to adjust. Look - there they are now looking for a place to eat. Too bad the nearest Indian restaurant is 2,000 kilometers away. There's Mrs. Singh doing some grocery shopping. Sorry Mrs. Singh - there's no curry in this supermarket! It looks like they'll have to eat Canadian food for a while. But, as you can see, the Singhs seem to be adjusting nicely. See Mr. Singh carving that big Christmas turkey? Don't forget the gravy!

The Canadian Immigration Agency: Helping strange foreigners become normal people.

How to Fix Anything: A User Guide for Ladies
Hey ladies - fixing things is easy! Just follow these simple steps:

If it doesn't have too many moving parts or any sharp edges - Ask your son for help, or just call on a neighbour's boy down the street. They should be able to help you! And no - you don't have to pay them - sincere praise from a grown-up is all the reward they need!

If it has lots of moving parts or sharp edges - Ask your husband.

Note: If you don't have a son or husband, or access to one, then you're just plum out of luck!

What Does a Technical Writer Do?
(Another high school education film.)

Meet Joe. He's a technical writer. He writes the instruction manuals that go with products so that people can understand how to use them. It's an important job, because if people can't use the product, then they'll have to call up the company, which then has to immediately send a local repairman out to fix the problem, at the company's expense, of course. We sure don't want that to happen, so it's important that anyone can understand what he writes.

The typewriter is the main tool of the technical writer. Today's typewriters allow you to go back and correct an entire word! Think of that - no more wasted paper sheets. We are truly living in a modern age.

Here's Joe at work now. He is working on a very important guide - a user manual for a washing machine. The first rule of technical writing is that you have to write with the end user in mind. This means that Joe must write the guide so that even a woman can understand it.

Joe is chatting with Henry, the designer of the washing machine, as they each relax with a cigarette. Henry has to be careful not to smudge the draft of the guide with his highball. Afterwards, Mr. Singh comes by to clean up the big mess they made.

Joe then takes an extended lunch with Betty, his attractive secretary. He's probably going to talk about all of the wonderful documents he's working on. There they are now, back from their long break. It must have been an exciting discussion because they both look so tired! Joe and Betty sure do spend alot of time together - it can only mean he's working on a really big user guide!

Well, it's been another full day for Joe as he comes home. Joe makes a good living as technical writer, allowing his wife and family to have nice things. Doesn't Joe's daughter have a swell dress?

So consider becoming a technical writer - your wife will be glad you did!

Remove bomb; replace with cupcake

2011-06-23T14:21:00.002-04:00

Informational high-tech agents (a.k.a. "hackers") working for British intelligence broke into an al-Qaeda website and replaced one of the site's documents.

When end users tried to download a 67-page instruction guide entitled “Make a bomb in the kitchen of your mom”, they instead got a page of - wait for it - cupcake recipes.

"It's a good thing," as Martha Stewart would say, since cupcakes tend to be less lethal than bombs.

And who said informational workers don't kick ass?

Terrorists. I hate those guys.

Topical Docs

2011-06-02T11:08:00.001-04:00

In a basement deep below the University of Victoria, scientists are assembling a fantastic new tool that will allow them to peer more deeply into the inner universe than ever before.

The Scanning Transmission Electron Holography Microscope (STEHM) will able to zoom in to 40 trillionths of a meter, 2.5 million times smaller than the width of a paper sheet.

This new microscope is so sensitive that even a passing cloud could affect its readings. Its specimens will be so tiny that a conventional electron microscope is needed just to prepare them. Scientists will be able to make detailed measurements of previously unknown sub-atomic characteristics. In fact, they will actually be able to move individual atoms.

I've always been fascinated by the reality that all matter in the universe is made up of atoms, and that all atoms are comprised of only three components, or particles: protons, neutrons, and electrons. Simply by assembling these three particles into various combinations, one can create anything from water, stone, plants, and people, to planets, stars and galaxies. It is the modularity that is so intriguing - from three parts, one obtains all.

Information development has caught up to this model of reality. The basic component of a document is no longer a page, chapter, or book - it is a topic, in a paradigm known as topic-based authoring.

Topics can be merged, moved, and grouped in endless combinations. There is a natural hierarchy formed when you assemble topics into larger chunks. This hierarchy corresponds to the building blocks of matter, as follows:

1. A topic is to a document what a subatomic particle (such as an electron) is to matter. It is the basic component in a document. Each topic can and must stand alone.

2. Combinations of topics are like atoms. They form a section of a document containing a group of related topics. This corresponds to a book within an online help TOC, or a chapter within a book.

3. Groups of sections are like groups of atoms, or molecules, for example, a water molecule. These correspond to an entire document.

4. Groups of documents form a library, which is like the various molecules combined together to form the complex matter, or compounds, that we encounter every day, everything from plastic to clothes to hamburgers.

Summing up, we have two very similar hierarchies:

Components of Matter: Particle - Atom - Molecule - Compound
Components of Information: Topic - Section - Document - Library

The base component is the particle and topic. Merging the names particle and topic, we get topical.

Which can only mean that all our documentation should indeed be topical.

The IT Guy Says: Back it up!

2011-05-25T10:08:00.004-04:00

Doctors constantly tell us to eat right, exercise regularly, and avoid smoking. Yet there are many doctors who are smoke, are fat, or are fat smokers. Hence the term, "doctors make the worst patients".

We who work in information technology (IT) are no different. A doctor implores people to live healthily; IT professionals implore people to back up their data. Yet there are many IT degree professionals who fail to do this, thinking that hard drive failures and accidental file deletions don't apply to them.

Technical communicators commit two sins in this area. Many of us don't back up our files, or if we do, we don't communicate to others how to do this. I am guilty of these crimes, and sentence myself to writing this article explaining my own multi-faceted approach to file storage and backup:

Back Up Your Files Already!

I have a three-stage approach to file back up and storage. At a minimum, you should do stage 1, but consider the other stages also.

Stage 1: Buy an external hard drive
Buy an external USB hard drive, attach it to your computer, and back up your files every day. Now, if you don't have too many files, you could use a memory stick, but its performance can be quite slow compared to the hard drive. Besides, who amongst us really has only a few GB of data?

External hard drives come with their own backup software, or you can use a third-party program, many of which are free. I like Microsoft's SyncToy, which you can set up to synchronize files on your computer to your backup drive.

I recommend setting up your backup software so that it only contributes files to your backup drive, and does not delete them. Although you'll end up with extra files on your backup drive, it's better to have them and not need them than to need them and not have them.

Stage 2: Use an online back up service
While at a minimum you should back up your files to an external hard drive, this practice has one major limitation. If your computer and backup drive are stolen or destroyed, you are out of luck. One inexpensive way around this is to back up your files onto a CD or DVD and then store this in another location. The problem, of course, is that your file collection keeps changing.

An online backup system backs up all your current files to a secure location on the Internet. Even if your house burns down, your files are still available.

There's many online services to choose from: I use iDrive which had the best pricing: 5GB for free, or 150 GB for $50/year, about $4 per month. You can configure it to automatically back up files as they change, thus ensuring that your backup always reflects your current file list. In addition, you can access your backed up files from any computer with Internet access.

Stage 3: Move to the cloud
All of my non-financial information lives on the cloud (the Web). This includes Google Docs for documents and spreadsheets, Gmail for email, Google Calendar, an iGoogle "to do" list, and this blog.

The beauty of having as much of your data on the cloud as possible is that you can log into any computer and access your data. When you combine cloud storage with an online backup service, you have full access to your digital world anywhere, anytime.

The downside is that security becomes an issue. That's why it's important you don't store any sensitive information online, such as financial or banking information. The balance between security and convenience did not begin with the Internet, nor does it end with it. For example, credit cards offer convenience, but also the potential for fraud. As with all things, you need to use your best judgment.

***

This is my three-stage approach to backup. Feel free to describe your approach by commenting on this article.

Ultimate Doc Tease

2011-05-24T10:16:00.002-04:00

The Ultimate Dog Tease YouTube video has been viewed 30 million times. It's a hilarious clip of an unseen owner unbearably teasing his dog about food. If you haven't seen it yet, watch it now, then return to this article.

***

Pretty funny, eh? Andre Grantham, the creator of this video and several other talking animal videos, is from Halifax, Nova Scotia. He was unemployed when this video was released, but soon received a job offer.

What makes this video so funny is its simplicity. There are no special CGI talking animal effects - the movement of the dog's mouth is all natural, as is the dog's ever hopeful expression.

Because we don't see the owner talking, and because the "talking" done by the dog doesn't match the dog's mouth exactly, it would be quite easy to dub in your own script. I'm not a video editor, but here's the script I would write for this video:

Me: So I got this draft back.
Dog: Yeah.
Me: Yup - a SME took the time to review it, can you believe it?
Dog: Yeah.
Me: Anyway, I looked through the whole draft...
Dog: Looked through the draft, yeah.
Me: And the reviewer wrote on it..
Dog: Yeah.
Me: NEEDS WORK!
Dog: Ohhhhwwww.....you're kiddin' me.

Me: Then I started working on this other guide.
Dog: Yeah.
Me: A user guide.
Dog: A user guide, yeah.
Me: It had lots of really nice screenshots. Very pretty.
Dog: Yeah.
Me: We were all set to release the guide, but then you know what?
Dog: What?
Me: The marketers changed the screen design!
Dog: Ohhhhwwww.....

Me: Then my boss called me into his office.
Dog: Yeah.
Me: He said we'd be getting a brand new content management system.
Dog: What would be in it?
Me: Well, it would have versioning, multiple outputs, workflow management..
Dog: Workflow management, yeah.
Me: ...be DITA-based and fully customizable.
Dog: Yeah.
Me: My boss said we could get it real soon.
Dog: Yeah.
Me: But to pay for it...
Dog: Yeah.
Me: ...he'd have to lay off me and half the writers!
Dog: Ohhhhwwww.....

A Life or Death User Guide

2011-05-19T15:31:00.007-04:00

The state of Oregon will soon ban the sale of suicide kits in response to the tragic death of 29 year old Nick Klonoski, a depressed man who killed himself using a kit he ordered through the mail.

These kits cost $60 and contain a plastic bag that fits over the head, a plastic tube for attaching to a tank of helium gas, and detailed instructions.

Although Oregon allows doctors to help terminally ill patients end their lives, it certainly has not legalized suicide for mentally ill individuals. The fact that anyone can easily purchase these kits has spurred the government into action.

This very sad case raises a disturbing thought experiment for information developers:

Imagine you were forced, under threat of death, to develop the user guide for this suicide kit. You are given all the technical specifications and procedural information, but you have permission to write any text you wish. You know that some of the users are not terminally ill, but are instead depressed.

What information would you include in your guide, which is literally a "life and death" document?

Knowing our users, we would include a warning such as:

WARNING! This kit is only intended for people who are terminally ill. If you do not have a physical illness, or think you might be depressed or suicidal, please call 911 or the local suicide prevention number....

Now imagine the same scenario, but this time the manufacturer of the kit must approve your draft. They have told you that you cannot include any type of warning for depressed people. If you do, it will be deleted.

Now what do you write? How do you give a user information without explicitly stating it? Simple - by implicitly stating it, as follows:

Note: This kit is only intended for patients that have been diagnosed by a doctor as having a painful and terminal illness.

The irony here is that this note could be more effective than the traditional warning. It does not explicitly tell a depressed user what to do. Instead, it subtly suggests that this guide does not apply to them. It plants a seed that could save the user's life.

Returning to the real world of ordinary documentation, we often have to balance what a user wants to know against:

what a user needs to know (even if they don't want to know it)
the requirements of the manufacturer

This nightmare scenario of the suicide kit guide illustrates how difficult it can be to balance these competing needs and wants.

Now, most users ignore documentation, and certainly most depressed people would ignore both the warning and the note. But not all of them will, and if the inclusion of this paragraph saves only one life, it will be worth it.

As the Talmud, the ancient book of Jewish law, states:

"Whoever saves a single life, it is as if he saved an entire universe."

Lessons from the 2011 Canadian Election

2011-05-11T12:53:00.005-04:00

The results of Canada's recent federal election were truly stunning. If you're not Canadian (or are but have been living under a rock), here are the results:

the Conservatives won a majority of the districts (or seats), capturing 167, up from 143
for the first time ever, the NDP formed the official opposition by winning 102 seats, up from 37
the Liberal party was reduced to third place, winning only 34 seats, down from 77
the separatist Bloc party in Quebec was reduced to "junk bond" status, down from 49 seats to only 4, out of 75 seats in that province

What can technical communicators learn from all this?

Let the learning begin...

Lesson #1: Stability and change can co-exist

The election results were paradoxical to say the least. Only 40% of Canadians voted for the ruling Conservative party. However, voters also left the Liberal party in droves, elected more NDP MPs than ever, and dumped the ruling Bloc party in Quebec.

Did voters vote for change or for more of the same? They did both. Due to the peculiar nature of our first-past-the-post voting system, the Conservatives gained only 2% in the popular vote, but 17% more seats, more than enough to obtain a majority. At the same time, the NDP gained 13% in the popular vote, but increased their seat count a staggering 175%. The numbers don't lie, but they sure tell a funny story.

Existing documentation projects, as well as software, share a similar paradoxical quality. They must be stable enough so that current users can continue to use them without getting lost or confused. At the same time, documentation is constantly evolving as the product changes and the documents are updated.

Striking the right balance between stability and change is one of the great challenges of our profession. That's why is often liberating to work on new projects, but even then, they often need to be developed within existing standards.

Lesson #2: Sometimes less is more

NDP leader Jack Layton gained more seats and is now the official opposition party. It may seem the NDP gained more power, but strangely, they may have even less. This is because previously the NDP was one of three parties that held the balance of power. The NDP could and did threaten to join with the other parties to bring down the government. Under the current Conservative majority government, the NDP have lost that power. That is, they won, but they also lost, showing that less is sometimes more.

"Less is more" is one of the axioms of our profession. Shorter, concise paragraphs and topics are much more powerful and effective than longer ones. In other words, "when in doubt, leave it out."

Lesson #3: Hubris is death

As described previously, the leaders of the Liberal and Bloc parties joined forces with the NDP to bring down the government and force an election. Bloc leader Gilles Duceppe believed he would continue his winning streak in Quebec. Liberal leader Michael Ignatieff hoped to become the next Prime Minister, or, at the very least, increase his party's seat count. Each of them conveniently provided the noose around which to hang their own neck.

Not only were the seat counts drastically reduced for these two parties, both leaders lost in their own riding. They had no choice but to resign, leaving each of their parties in tatters.

If there's one thing the public cannot tolerate, it is the politician who gives even the slightest impression that they are "owed" a victory. Arrogance, hubris, and a sense of entitlement are all a death sentence in politics.

Political campaigns are one long job interview, where each leader tries to convince you to "hire" them through your vote. Hubris is the last quality you want to exhibit in an interview. You need to strike the right balance between confidence and humility. You want to show that you know your stuff, but are not a "know it all".

In addition, technical communicators are often called on to be user advocates. We push for simplicity, clarity, and consistency, not just in our documentation but in the products and services we document. However, we must realize we do not own these products: the product managers and others who work directly with the end user do. We can advise, but we cannot dictate, for that is the essence of hubris.

Lesson #4: "Top" and "bottom" are interchangeable

The Conservatives are now on top; the Liberals on the bottom. This is not a permanent arrangement. Unless you are living in a one-party state, the ruling party never stays in power indefinitely. As high as the winning party is now is exactly how high the losing party will eventually be. Top and bottom are but temporary states.

Now, if you have made the transition from a traditional, book-based authoring environment to a topic-based one, this principle becomes apparent. Instead of creating pages, chapters and books, you create individual topics that can stand on their own. You assemble and organize these topics into logical groups, such as the TOC folders within an online help system. You can easily move these topics around, quickly relocating them from the top of a document to the bottom, or anywhere else. Again, top and bottom are but temporary states.

Lesson #5: Take your time

The Liberals now have about four years to rebuild their party. They should use the time wisely, and not rush, otherwise they will never recover. A "sub-lesson" to this lesson is that those who do not remember the mistakes of the past are condemned to repeat it.

For any document or documentation process, especially if it is new, take your time. It's a cliché to say, but most people don't plan to fail - they fail to plan. More documentation projects fail or are much more difficult than they need to be because no-one took the time to stop and carefully analyze the requirements and implementation process. They just dove right and started developing content, without first deciding how the content would be used or identifying who would actually be reading it.

I often hear the refrain "we don't have time to do that". I would counter that you don't have time not to. The Liberals have all the time in the world - do you envy them?

Lesson #6: Branding is everything

The final and most important lesson from the election is the importance of branding.

A brand is the idea or image of a product or service that people can connect with. Branding is the communication of this idea (through marketing) so that it is perceived as being uniquely recognizable from other products or services.

When we think of brands, we typically think of large companies such as Coca Cola, Microsoft, Dell, IBM, and Toyota. However, brands can be applied to anything - even you. (We'll get to that in a minute.)

Political parties know the importance of branding. To put it mildly, the Liberal brand has been suffering for the last few years. Their continued drop in popularity and seat count was inevitable, no matter who was leading the party. The Bloc's brand was associated with sovereignty - a concept that most Quebeckers seem to have rejected for now with their embrace of the federalist NDP.

The NDP's branding, especially in Quebec, was simple and brilliant. One of their Quebec TV ads had dogs barking at each other, with the tag line: "Always the same debates that lead nowhere", followed by "It's time for a change. Work together." This branding was so powerful it catapulted the NDP from one seat in Quebec to 58. Some of the new MPs were university students, including a nineteen year-old voting for the first time in his life. Another student did not even live in the riding she was running for, and was on vacation for part of the campaign. It did not matter; such is the power of branding.

Think that branding doesn't apply to you? Think again. When you have a job interview, and even after you've been hired, you are a brand. You must demonstrate and transmit the key qualities that define you as a technical communicator, and a person. These could include: outstanding communication skills, efficiency, patience, knowledge, technical expertise, a team player, and above all, an improver. In an interview, you must clearly show in your work experience that you are passionate about your profession and have actively enhanced the quality of the documentation and the documentation process. That is your brand - your brand is you.

These are the lessons from the election. There are many others. Anyone who wants to discover these has my vote.

A no-good lying email

2011-05-02T17:15:00.001-04:00

Imagine my excitement when I received the following email after subscribing to a magazine:

The latest edition of your magazine is now available. Print subscribers: your issue has just been put in the mail. Please watch for it in your mail box in the coming days.

Woo hoo! I would soon be receiving my first printed issue of the magazine. Oh boy, I could hardly wait.

But I did wait. And waited, and waited, and waited some more.

Finally, after waiting about a month, I called customer service. The service rep checked his computer-database thingy, and proclaimed that due to the way new subscriptions are processed, my first edition would not be arriving for another week.

In the words - the email I received was a bald-faced lie. I suggested to him that, er, maybe he should look into this, because it's "rather disconcerting" to receive an email stating something which is, in fact, not true.

Which was a polite way of saying that the magazine had done a piss-poor job integrating their mailing and emailing systems.

This is a common problem. It happens because there are two types of information in this world:

Type A: officially distributed information
Type B: the true version of Type A

Because most of the people running organizations are not technical communicators, they have no problem mixing up these types. They will cheerfully send out information they know is incorrect, with the mantra that "hey, nobody reads these things anyway, so what's the point in trying to get it right?"

As technical communicators, this should make our blood boil, if not explode. Creating, sending or distributing inaccurate or false information is a crime against humanity. Unfortunately, we are the only judges and prosecutors for these transgressions. We're also ultimately the only ones who care enough to make it right and have the skills to do so.

But for now, I'm dropping the charges.

Name that document

2011-05-02T16:33:00.000-04:00

I saw a document on the news today with two entries, each followed by a number.

It's not a TOC.

It's not an index, either.

It was a hand-made sign summarizing yesterday's historic event: the irreversible deletion of one (1) Mr. Bin Laden:

OBAMA: 1
OSAMA: 0

I couldn't have documented it better myself.

Failsafe

2011-04-25T14:32:00.003-04:00

President Obama recently proposed an intriguing solution to deal with his country's ever-growing debt: a "failsafe" trigger. Here's roughly how it would work: if the debt as a share of the economy (the debt-to-GDP ratio) does not drop below a certain ratio by a certain date, then spending cuts, tax increases, or both would automatically be implemented.

Politically, it's a brilliant solution, as it transfer the onus of decision-making from the politicians to the bureaucrats, as they are forced to make the deep but necessary cuts to lower the debt, currently a nightmarish $14 trillion.

A failsafe system can be applied to any process. It is comprised of:

a specific, measurable goal to be achieved
a date or time period by which the goal must be met
a specific, measurable action that will be taken if the goal is not met

A simple example is weight loss. For example, you could set a goal of losing 3 kg. in two weeks. If you fail to meet this goal, you would have to lower your intake by 300 calories, exercise an additional 30 minutes, or both. You would repeat this failsafe system until you have reached your ideal weight. Then comes the tough part: maintenance. A second failsafe system ensures you stay on track.

Could a failsafe system be developed for documentation? It could, if we can define a measurable goal. However, objectively measuring the quality of documentation can be difficult. To obtain an objective, measurable goal requires carefully observing a user interact with the documentation.

Some of the measurements of documentation could include:

the success rate at which the user finds the relevant topic
the length of time required for the user to find the relevant topic
the average rating given a topic by the users

Another measure could be the number of contacts (phone calls or emails) to technical support. This could be broken down further into:

contacts made due to incomplete or inaccurate documentation - for example, a procedure is missing or a field is not explained clearly
contacts to report specific documentation problems - this occurs when users give direct feedback on the documentation

After deciding what it is you are going to measure, you can then set a goal based on a specific date or time period, for example:

improving the success rate by 15% over the next 3 months
reducing the topic search time by 20% over 6 weeks
reducing technical support contacts by 10% by August 1

Finally, you need to select an "action item". That is, what specific action will be taken if the goal is not met?

Ideally, the action would be be implementing a thorough review of the documentation (or portions of it) based on feedback from users or internal staff such as QA, Business Analysts, Product Managers, and so on. This could include creating a "closed feedback loop" whereby users can directly comment on any topic; the results are then sent to the appropriate writer who will make the necessary changes.

Is this idealistic? Yes. Many technical communicators are already stretched to the limit, so asking them to set aside time to improve their existing documentation is not always realistic. However, for those who are fortunate enough to implement such a failsafe system, the end result is documentation set that actually saves a company money.

The Chinese Tent

2011-04-14T13:21:00.023-04:00

Welcome to the Chinese Tent...

Imagine a large tent, and in it, a person who speaks only English. We'll call this person the respondent. Outside the tent is a person who speaks only Chinese. We'll call this person the questioner. The questioner writes a message in Chinese and passes it to the respondent through an opening at the front of tent. The respondent receives the message, then using an infinitely complex look-up system, matches the message on the card with a corresponding card containing a response in Chinese. The respondent delivers the pre-written response back to the questioner.

From the perspective of the Chinese questioner, the English respondent has read the message and understood it, demonstrating intelligence. However, has the respondent actually responded intelligently? Remember, the respondent does not understand a word of Chinese - he has simply matched up a pre-defined response to the received message.

This is not intelligence, but an elaborate forgery. The Chinese Tent exposes the folly of thinking that computers can actually be intelligent. Computers can simulate all sorts of reality; this does not make the reality they simulate real.

When a computer runs a virtual stock market exercise and makes millions of virtual dollars, the user does not become wealthy. When a computer runs a weather simulation that has 40cm of rain falling in one day, the user doesn't get wet. Yet when a computer simulates intelligence, we all rush to believe it's actual intelligence, and not a pale imitation.

It all comes down to definitions, something technical communicators are very fussy about. So how do you define intelligence? Here's one standard dictionary definition:

"the capacity for learning, reasoning, understanding, and similar forms of mental activity; aptitude in grasping truths, relationships, facts, meanings"

The key word here is understanding, which implies consciousness; the knowledge that one exists. This is something that computers simply don't have.

However, if you define intelligence as the ability to give a meaningful response to a question, then computers could indeed be intelligent. A recent example of this was Watson, a super-computer developed by IBM. Watson was a contestant on the Jeopardy game show, beat his human opponents and won a million dollars.

Depending on the definition of intelligence you choose, Watson is intelligent or simply another version of the Chinese Tent. It is able to analyze questions and supply responses, but if you were to ask it how it felt about winning against humans, it would have no response.

What, then, is an "intelligent" document? It is one which understands the information requirements of the user and then seamlessly delivers them. Now, there are help systems that allow a question to be entered and then try to give a relevant response, but these are very complex to set up and have mixed results. A far simpler solution is to create a complete and meaningful index, one which anticipates all the strange and wonderful ways a user might look up a topic.

An index also has the advantage of revealing potential gaps in your content or the index itself. For example, you may have the following index entries:

records,

creating

editing

deleting

files,

creating

deleting

Where is the entry for editing files? Doh!

A complete and meaningful index is an intelligent index, and helps to make your document intelligent. Of course, once a user finds the topic they are after, it has to be intelligently written. This means that the topic should answer questions, and not raise them. Questions such as:

What is this object, thing or concept?
What is it used for? Why would I use it?
How do I perform a specific task?
What are specific things I need to be aware of?
What things or tasks are related?

An effective document, then, is one giant answer book. An intelligent document gives the user the answers they need, without the user even realizing the effort they made to find them.

The Governing Dynamics of Documentation

2011-02-22T10:28:00.002-05:00

Game theory is a specialized field of mathematics that analyzes choices and results in strategic situations, or games, as the players try to maximize their success. It can be applied to practically any situation where one is making a choice for personal benefit, for example:

choosing a restaurant
hiring a worker
buying and selling stocks
deciding who to marry
playing poker (or any other game)

Game theory has been applied to such diverse fields as: economics, evolutionary biology, engineering, political science, psychology, philosophy and business management. Google even uses it to maximize the advertising revenue generated from their AdWords. All of these areas require making the best decisions possible in order to create the maximum benefit.

Game theory takes into account the fact that humans are essentially self-centered, that is, that we tend to act in a way that we think will be best for us. Even when we appear to be selfless, we're still acting in our own self-interest. For example, giving to charity gives us the benefit of feeling that we're doing a good thing, a benefit that we're willing to pay for.

The Nash equilibrium (also know as governing dynamics) is a set of game theory strategies. It states that the individuals in any situation will benefit the most if they do not only what is best for them individually, but also what is best for the entire group.

This equilibrium was developed by the mathematician John Nash, who was profiled in the wondrous film, A Beautiful Mind. The film gives a graphic example of his theory:

A group of men and women are at a bar. Each of the men wants to pair off with each woman. However, one of the women, a blond, is more attractive than the others. The question is: should each man go for a less attractive woman, or try for the blond?

The Nash equilibrium implies that no man should try to pick up the blond. Odds are they will all be rebuffed. If the men then try to go after the other women, they'll most likely be rejected because each women will know that they were the man's second choice. The best strategy, therefore, is for each man to try to pursue a woman other than the blond.

To sum up: the Nash equilibrium states that in any situation involving trade-offs, the maximum benefit is achieved if everyone is making the best decision they can taking into account the decisions of the others.

The Nash equilibrium has been applied to an amazing variety of areas including:

arms races
technical standards
bank runs
currency fluctuations
traffic flow
auctions

Nash's theorem was so ground-breaking that in 1994 he won the Nobel prize in economics for his theorem. (There is no Nobel prize for mathematics.)

The philosophy of this equilibrium can be applied to information development on two different levels: within the architecture of information objects and to the information development process.

Documentation Objects

All documents contain sets of objects that can be thought of as "players" in a game. These objects include:

topics
cross-references
TOC entries
index entries
graphics

In addition, documents themselves form objects in a documentation set, as part of a group of related documents.

Conflicts will arise if there are two or more objects within each of these areas that are difficult to distinguish. Examples include:

topic with similar names, such as Overview and Introduction
index entries that begin with the term removing and others that begin with the term deleting
two graphics that describe the same thing but in a slight different way
using the same term to describe different things
guides with similar names, for example an Administration Guide and a Technical Guide

Conflicts such as these create confusion for the end user, because they have no way of knowing which is the "correct" version. This creates an unnecessary game-like situation for the user, as they struggle to pick the winning object.

To avoid this, all documentation needs to be carefully reviewed and purged of all conflict. The end result is a series of objects that play nicely together. What is best for each individual documentation object is also best for the group of objects; the very essence of governing dynamics.

Multiple Authors

The Nash equilibrium can be applied even more directly to the information development process in a multi-author environment. Many organizations have content management systems in which multiple authors can create, edit and manage their documentation.

While such systems can create a more balanced workload, the potential for conflict is enormous. Even if the system only allows one editor at a time (a standard feature of any content management system), it's still easy for writers to get into editing conflicts in which whoever updates last "wins".

This is not a technical issue but a management issue. Writers must understand they are not competing against each other but against incomplete and inaccurate documentation. The end user wants relevant information, and is not interested the writers' turf wars. As the Nash equilibrium implies, writers working on common documentation sets need to know that what is best for the group is also what is best for each of them.

There are probably few areas in life to which governing dynamics could not be applied. Therefore, the idea that "life is but a game" is far more true than we can possibly imagine.

How to update a document - NOT!

2011-02-17T11:12:00.000-05:00

Canadian International Co-operation Minister Bev Oda needs to work on her document management skills. She hand wrote the word 'NOT' in an official document, completing changing its meaning so that federal funding would be denied to an organization. In doing so, and in trying to cover it up later, she signed her political own death warrant.

All information developers need to be mindful of changes. Whether using the track changes feature in Word, or some other system, ideally we should record all the changes made to a document. This is especially true if your documentation is going to be translated.

Tracking changes and using version control also allows you to revert to earlier versions if needed. Too bad Ms. Oda wasn't using such a system. It might have saved her much grief.

Or NOT.

Meet the new boss, same as the old boss

2011-02-17T10:59:00.000-05:00

Mr. Mubarak is updating his resume. After 30 years in power, he was fired after 17 days of massive protests in Egypy. Apparently, his end users weren't too happy with how he ran the country.

The populace is celebrating the "new Egypt", but this could very well turn out to be the vapourware of the century. The new boss, Omar Suleiman, worked for the old boss, so it's difficult to see how things will actually change. This isn't Egypt 2.0, but more like Egypt 0.0 with some patches.

Moving on to actual software, many technical communicators detest the tools and systems that they work with. It's tempting to simply revolt and dump the current process, replacing it with anything else.

However, any new tool or system must be viewed with its final result in mind. The two primary questions to ask are:

1. Will it improve the quality and efficiency of the information development process?
2. Will it improve the quality of the documentation itself?

If not, then as poor as the current system is, at least it works.

Whether changing a country or a process, we must remember George Orwell. His classic novel Animal Farm wonderfully documents the failure of the Russian revolution. The men represent the brutal Czarist government; the pigs are the communists. The men are overthrown by the pigs, who turn out to be just as brutal.

The final words of Animal Farm are the most haunting:

"No question, now, what had happened to the faces of the pigs. The creatures outside looked from pig to man, and from man to pig, and from pig to man again; but already it was impossible to say which was which."

A fat man, a madman, and a runaway train

2011-01-06T15:21:00.004-05:00

Imagine this scenario: a runaway train is hurtling towards five people tied down to a railway track by a madman. You can pull a switch to divert the train onto another track where another person is tied down, killing the one person, but saving five.

Should you throw the switch? Most people will say yes, reasoning that it is better for one innocent person to die than five.

Now imagine this scenario: The same train approaches the five trapped people. This time, you are standing next to a fat man on a bridge over the tracks. If you push the man onto the tracks, his massive weight will stop the train but will kill him. However, the other five people will again be saved. So, do you give him a push?

Most people will say no, because even though the end result is the same (the man will be killed), the killing will be direct and deliberate. In the first scenario, killing the man is an indirect effect of pulling the switch.

You can vary this scenario endlessly. What if the fat man was also the mad man? What if the one person tied up was your spouse, parent or sibling? What if the five men were all convicted murderers who had escaped?

There is an entire science devote to ethical and psychological issues called experimental philosophy, or X-Phi and even Trolleyology. Experimental philosophy uses data gathered through surveys of hypothetical moral scenarios. It's a scientific attempt to draw conclusions on how people reach moral decisions. In doing so, X-Phi is a strange brew of science, psychology and philosophy.

X-Phi is not just a serious of extended thought experiments: it has very practical applications. For example, the recent financial meltdown was caused by many people making various choices and judgments. These people included not only the lenders and administrators of high risk loans, but the recipients of these loans, and the various government agencies involved in regulating the loans. All these people made what in hindsight are appallingly bad choices. However, at the time, these choices may have seemed quite reasonable. By studying the factors that lead people to make bad choices, the hope is they won't make them again.

Technical communicators are often faced with ethical dilemmas as a result of conflicting needs and wants. These include:

the need to give the user all the information they require and want and
the need to withhold information that is not required, and which could overwhelm or confuse the user

the desire to work in harmony with the people who are developing the product being documented and
the need to be an end-user advocate which can involve suggesting product changes that may take considerable effort to implement

the desire to work well with other writers on a team and
the need to ensure the documentation is of the highest quality through peer reviews, which can involve constructive criticism of another writer's work, or of your own

These conflicting needs can arise in a variety of ethical dilemmas that a technical communicator could face. Here are few examples to ponder:

You're having trouble getting the required information about a certain feature from one of the subject matter experts (SMEs). The deadline for the release is fast approaching, and the SME is nowhere to be found. You approach the desk of the SME and see a folder on top with the title of the exact feature you need information about. However, the folder also has a large note, stating: DO NOT REMOVE. Do you borrow the folder, with the intention of giving it back as soon as you're done with it, but knowing that the SME will notice the missing folder?

Now imagine the same scenario, but this time, you know the SME is away, and will therefore not notice the missing folder. Does this affect your decision? What if it was the same folder, but the SME accidentally left it on your desk? The SME won't know you have the folder, but the folder still has the same note saying that the folder was not to be removed from their desk.

Another scenario: You have co-authored a user guide with another writer. Each of you have done exactly half the work. However, your manager believes you are the sole author, and praises you for writing such a fantastic document. If the other writer will never learn about this conversation, do you tell your manager you are not the sole writer? What if you knew your manager was deciding which one of you to promote? Would you then tell your manager the truth, again, assuming that the manager would never find out that you were not the sole writer? What if you had done 60% of the work? 75%? 80%? What if the other writer had previously left the company?

The point of these mental exercises is to pinpoint the exact conditions under which we believe a choice becomes immoral. By isolating the factors that influence our choices, we can learn much about the way we think and behave.

And no - I have no intention of stating what I would do in these various situations. In the book of life, the answers aren't in the back section.

A primer on primers

2010-12-27T12:19:00.002-05:00

A primer (rhymes with dinner) is subset of information included in an encrypted message. The recipient of the message uses the primer to decode the message. In other words, the key to translating the message is contained within the message itself.

A spectacular example of a primer was presented in the film Contact. An extremely long and complex message written in a mysterious code is received from deep space. The scientists scramble to decode the message, but are unable to because they cannot correctly align the symbols at the edges of the thousands of pages contained in the message.

In this scene, three of the pages appear on a large monitor:

Someone discovers that the documents are actually three dimensional. By "folding over" the pages into each other to form a virtual cube, they magically line up, as shown here:

Not only that, within the edge of each page is the primer, the key to translating the message into Earthspeak, including the symbols for true and false:

Using the primer, the scientists are able to translate the message into a user guide that describes how to build an enormously complex machine.

* * *

All documentation contains primers to help the user understand the contents of the document.

Within traditional documentation, primers include:

a section explaining the contents of the guide and its audience
a table of contents and index to guide the reader to the correct topic
standard document conventions describing how various items are presented in the guide, including: UI elements, paths, code samples, optional items, notes, warnings, and so on
instructions on how to view, search and annotate the document (if possible)

Through these items, the information required to understand the document is included in the document itself. It is the inclusion of this information within the larger document that enables this information to be a primer.

In additional to external primers (which are visible to the end user), you can also create internal (private) primers. These are elements which only you and the reviewers can see, and include:

questions and comments for reviewers, tagged so that a reviewer can quickly navigate to them
notes that apply only to the technical writer, for example, reminders of tasks the writer needs to complete

Again, the principle of the primer applies: information to help understand the message is included in the message itself.

These uses of a primer, effective as they are, are nowhere near as powerful as those in the next generation of documentation: XML. XML strips away all visual formatting in a document, replacing it with pure coded and tagged text. This allows you to easily add meta-information (in the form of additional tags) within the document itself.

An example of this is an XML Schema Guide, a highly technical document describing various programming objects, classes and variables that developers can use. It is possible to create a traditional document that describes these things. However, when the schema changes, for example, if an object is renamed or deleted, the writer must manually update the document.

To avoid this, writers and developers can work together to create a schema that is self-documenting. That is, within the schema itself are documentation tags. By updating the information within these tags, and then using an application to transform the schema into a document, the writer can create a schema guide that accurately documents the objects in the schema and displays the relationships between those objects through hyperlinks.

Another example is an installation guide for an application that can be installed under a wide variety of environments. Each portion of the guide that applies to a specific environmental scenario can be tagged accordingly, for example:

operating system: [Linux], [Unix], [Windows], [Mac]
database: [Oracle], [MS SQL]
collaborative software: [Sharepoint], [Groupware]

Using an online application, the end user selects their specific environmental combination then submits a request for the guide. A custom-built guide is then automatically assembled. For the writer, this means no longer having to maintain multiple versions of the guide or use complex "if/then" statements throughout the document (e.g. if you are using Windows, then..., if you are using Oracle, then...)

The message for decoding the guide is literally embedded within the guide itself - the purest form of a primer.

An obvious blog entry

2010-12-21T11:22:00.004-05:00

Here's an important formula to know regarding your personal finances:

Total household debt (mortgage, credit cards, student loans, etc.)
divided by:
Annual disposable income (your yearly gross income minus taxes)
equals:
The ratio of household debt to disposable income

Canada's average ratio of household debt to disposable income has now reached 148%, a staggering new record, higher than the U.S rate of 147%.

It means that, on average, Canadians owe about one and half times what they make after taxes. For example, someone who earns $50,000 would owe a whopping $74,000.

As many financial commentators have noted, the solution to this problem is rather simple:
Don't spend more than you make.
-or-
Don't spend money you don't have.

These principles seem obvious, but they are obviously not that obvious, as millions of people continue to ignore them to their peril.

Other obvious principles you know are:

If you eat alot, you will get fat.
Exercise is good for your body.
Drinking and driving is dangerous.
Dropping out of high school is dumb.

We know these things, but often act as though we don't.

In technical communication, there are also obvious principles we often forget:

Technical communication requires good communication and technical skills.
Resumes and cover letters are documents; it's therefore a good idea to make them good documents.
Typos are really bad.
The best way to learn a new tool is to use it.
You can learn about technical communication by talking with people who are actually technical communicators.
It's a good idea to write with the end user in mind. They are the people who will be reading what you've written.

Make a new year's resolution to think of more obvious things, then practise those things. Principles are nice, but useless if not acted upon - obviously.

Help! My documents are leaking!

2010-12-07T13:27:00.003-05:00

The world has been gripped by one of the sexiest documentation events in history: the release of thousands of sensitive (and very embarrassing) diplomatic cables by WikiLeaks. If there was ever any doubt about the absolute power of information, it can be laid to rest now.

The "documentation manager" of this mess, Julian Assange, is now under arrest, not for leaking classified information, but for sex crimes. This is because sex crimes are sexier than informational crimes.

This event has graphically highlighted the two types of information that we deal with: internal and external. Any information developer who gets these mixed up will run into a world of pain. The problem is that because most information is stored in a "soft" format (on the computer or the web), it is easier than ever for private information to morph into public.

A fool learns from their own mistakes; a wise person learns from the mistakes of others. Let's learn from this and remember: any private information that you create can easily become public information. Thousands of examples of this happen every day including:

damaging emails accidentally sent to the wrong people, or deliberately forwarded to those people, or worst of all, made public (think Climategate)
error messages that were not properly reviewed and contain internal comments such as: tell the user not to be so dumb
any internal document leaked to the public

Therefore, any information you create or manage should include the following warning:

DANGER!

CONTENTS MAY EXPLODE OR LEAK.

HANDLE WITH EXTREME CAUTION!

Too many notes

2010-11-25T08:52:00.000-05:00

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

The Mother of all Confirmation Messages

2010-11-17T14:31:00.008-05:00

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.

The Medium is The Messenger

2010-11-16T14:14:00.003-05:00

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.

Jay Leno's User Guides

2010-11-10T09:48:00.014-05:00

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...

Black Box In The Cloud

2010-11-05T17:09:00.005-04:00

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.

You Lift Me Up

2010-11-04T10:23:00.001-04:00

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?

My Quantum-Mechanical Resume

2010-10-22T16:38:00.124-04:00

This article is based on a presentation I gave at the STC Toronto Career Day on September 26, 2010.

Confessions of a Hypo-Professional
There's a special breed of professional that you'll sometimes encounter: the hypo-professional, hypo being short form for hypocritical.

Examples of hypo-professionals include:

doctors who smoke or are fat (or both)
lawyers who break the law
accountants who don't file their taxes
plumbers who don't "plumb" in their own homes

These are professionals who don't apply the tenets of their profession to themselves. As technical communicators, we'd like to think we're not included in this sorry group, but let's be honest. Are all of your personal user guides and other documentation organized into nice, neat little piles that you can easily access? Are all your computer files organized into logical folders? Do you back up your files on a regular basis? Have you documented all your important personal information and kept it in a safe place?

Of course, most of our personal docs don't matter very much when job hunting. No one will decide not to hire you because you can't quickly locate your Blu-ray player user manual. However, there is one personal document that is very important, and that is your resume. It is the most important document you will ever work on. You are a technical communicator; your document is a form of technical communication; therefore the resume, being a document, represents you. If it is not the absolute best it can be, you are limiting yourself and your career.

Resume Length - The Debate Rages
There's a long-standing debate about how long and detailed a resume should be. Many experts say that a resume should be as short and simple as possible, because most readers have little time to read it. Others argue a resume should be as detailed as possible to ensure that the reader will not have to guess or assume anything about you or your qualifications.

The Novice
This dilemma stems from the fact that there are different user types for your resume, as there are for all documentation. At one extreme, there is the novice user, typically an HR representative. This person often knows very little about our profession, and will look at your resume and ask:

"What is HTML?....And how do you spell HTML?"

For these simple folk, your resume should be as simple and brief as possible. This means a length of one or two pages, and using simple, plain language that anyone can understand.

The Über Writer
The other extreme type of resume reader is the very experienced technical communicator, whom I call The Über Writer. This is someone who will look at your resume and say:

"I see from your resume that you used FrameMaker. I am currently an ultra-secret beta tester for FrameMaker version gamma-Z-theta. It is able to export multi-dimensional PDFs into hyperbolic space. Your opinion of this please...in 27 words or less."

This type of user demands far more detail than The Simple User. They may require a resume of three or more pages, filled with the technical details they crave.

Doubling Up
These very different users mean that you need to have two versions of your resume: a simple, brief one and a longer, more detailed one.

You send the simple one to the novice user, and the complex one to the experienced user.

Makes sense, right?

Well, not necessarily.

It could be that the person you thought was a simple user actually knows more about technical communication than you realized. Or perhaps they don't know, but they may know someone who does, and they may have forwarded your simple resume to this experienced user.

Conversely, perhaps the experienced user doesn't have time to read your detailed resume. Or maybe they want to forward your resume to someone who is less experienced. Again, there is a mismatch between the user and the document type.

Broken Attachments
One solution would simply be to attach both versions of your resume in an email. However, this method also has problems. Some users may get confused and not realize which document to open or save. They may end up only forwarding one of the documents. Many things can and will go wrong when sending multiple attachments.

What's needed is a different kind of document: one that gives the user a choice of version to read.

Note that what we are doing here is what our profession entails: defining a documentation problem and then solving it.

The Wonderful World of Quantum Mechanics
The solution involves a paradigm shift in how a document is viewed. The science that inspired the solution is quantum mechanics.

Quantum mechanics is a very strange area of physics. It's so obscure that even the scientists working in it have trouble understanding it.

Essentially, it says that we can never really know the exact location of a subatomic particle. The location is all based on probability or random chance.

It's interesting to note that Einstein did not like quantum mechanics; for him, it was just too "random". His famous quote "God does not play dice with the universe" neatly summarized his feelings.

Got random?
The fact is, though, that randomness is everywhere. Think of a light fixture or lamp anywhere in your home; one that you currently are not observing. The light may be on or off: you don't know; all you can do is assign a probability to either state.

Or think of a friend who may be in one of several emotional states: happy, sad, surprised, anxious, and so on. Unless you are observing your friend, you cannot know which state they are in; all you can do is estimate probabilities for each state.

The concept of applying probabilities to various states is ultimately the basis of the resume documentation solution.

The Solution - The Long and Short of It
Instead of having your short and long resume documents stored on your computer, imagine placing them both online and then cross-linking them to each other.

The short resume would include links (at the very bottom and top) to the longer resume. The longer resume, in turn, would have links to the short one. This way, the user has a clear choice of resume to read.

Maintaining your resumes this way means that if someone tells you they are reading your resume, you won't know which version, unless they've told you - all you can do estimate a probability. Even then, it doesn't really matter, for you know there is a 100% probability that they will select the version that they want.

This solution therefore allows your resume to exist in a quantum state: it's length randomly fluctuates depending on which version the user is reading.

This solution also borrows directly from one of the main tools in documentation: the hyperlink. An online help topic can include hyperlinks to other topics, allowing the user to explore the information in ever-greater detail. Using the same principle, your simple resume is linked to a more detailed version, allowing the reader to explore your experience in greater detail.

Get WIMPY
It goes without saying that your brief resume should be just that: brief. One way to ensure this is to count the number of words in your brief resume, and see if it exceeds a certain standard. However, this doesn't take into account the numbers of years you've worked in the field. A longer work experience could necessitate a longer resume, so we need a more meaningful measure for length.

The solution is to divide the number of words by the number of years you've worked in the field. For example, my brief resume has about 313 words, and I've worked in tech comm for 12 years. 313 words divided by 12 years = 26 words/year, which is quite brief. I call this number the Words Per Year factor, or WPY. You can remember it using the mnemonic: WimPY; may your brief resume be as "Wimpy" as possible.

Keeping It Simple
Another thing to remember regarding your brief resume is that it should be simple. In fact, all of your documentation should be as simple as possible, but no simpler.

What happens when the principle of simplicity is not followed? To give a graphical example, view the PowerPoint slide developed by General Stanley McChrystal, the US and NATO force commander.

This nightmare of a slide is completely incomprehensible - it is a spaghetti diagram of the worst kind.

Viewing this slide, we can safely say its developer is highly intelligent, incredibly methodical and totally insane. As the good General said: "'When we understand that slide, we'll have won the war," in other words, never, for no-one can comprehend it.

If I'd been asked to develop a PowerPoint slide that would describe how to win the war in Afghanistan, it would have the following text:

Winning the War in Afghanistan
We can win the war in Afghanistan.

To win the war in Afghanistan
Find the enemy.
Kill ‘em alot.

It may not be militarily accurate, but at least it's clear and comprehensible.

Making the Connections
There's another aspect of quantum mechanics that relates to resumes. It is this strange but true fact: if a particle is rotated, another corresponding particle will also rotate. Scientists have no idea why this happens; it's as though the two particles are somehow consciously linked in a wondrous two-way process.

You and your resume are similarly connected. It's obvious that as you change and gain experience, knowledge and skills, your resume will change to reflect this. But is the opposite true? That is, if your resume changes, will you change?

I believe you will. I've seen many people change after their resume has been properly reviewed and updated. People light up when many of their missing skills and accomplishments inadvertently omitted from their resume are finally included. These changes can give the person the confidence to apply for positions that they may previously not have. And if they land that new job, then they really have changed - all as a result of changing their resume.

Therefore, you and your resume are indeed inextricably linked, in the same way as the two particles; if one of these things changes, so does the other.

Here a link, there a link, everywhere a link, link
As demonstrated, linking is a common theme in this discussion. You are linked to your resume, and your resume itself is linked to another resume. As an online document, your resume is written in HTML, however the term HTML is actually a good example of meaningless information.

HTML is an acronym for Hyper Text Markup Language, a phrase that is utterly meaningless to most Internet users. From their perspective, HTML really stands for Helping To Make Links, which is exactly what an effective resume does. It not only links to another resume, it contains links to relevant websites (for example, to the companies you worked for, the schools you attended, and, of course, to the STC).

At a higher level, the resume is a link to you, and a link in the employer's mind from you to the job they're seeking to fill. It is, quite literally, The Missing Link.

Portability
Another advantage of an online resume is its portability; it's ability to be accessed anywhere and anytime.

Ideally, you should have your own website with a URL that is easy to remember, with a prominent link to your resume. No matter where you are, if you encounter someone who could potentially employ you (or who knows someone who could), you can simply give them your website address, and let them do the rest. In fact, if they have smart phone or PDA, they can view your resume immediately.

So if anyone asks me for my resume, I simply say, visit abrooke.net.

And view my portable, quantum-mechanical resume.

Information to die for

2010-10-22T13:31:00.001-04:00

Think informational design decisions aren't life and death? Think again.

As reported recently, poorly designed medicine labels are killing and maiming people. Two people died when they were accidentally administered potassium chloride (which is poisonous) instead of sodium chloride (which is not poisonous). This tragedy occurred because the vial labels for both these substances were very similar in design and appearance.

Neil MacKinnon, a pharmacy professor at Dalhousie University said it best: “If you ask any kind of front-line nurse or pharmacist, they would say ‘Gee, this isn’t rocket science, why can’t they make labelling clearer – put things in different size fonts, in different colours?’”

To which I would respond: Duh!

The current label for the potassium chloride looks like this:

Potassium Cholride
Concentrate USP

To avoid confusion, I would slightly redesign this label to read:

HEY YOU!!!

DON'T YOU KNOW THIS S--T IS POTASSIUM F---ING CHLORIDE!!?!!

IT WILL KILL WHOEVER YOU GIVE IT TO!!!

STOP NOW, YOU CRAZY MOTHERF----R!

Yes, it's crude, but so what?

If the bottle had had this label, there would be fewer dead people.

33

2010-10-14T10:53:00.000-04:00

It's a great day to be Chilean.

It's certainly true that the 33 miners rescued from the depths of the earth are heroes. Anyone who can survive over two months trapped in that pit of hell must be considered nothing less.

But as CBC's National Science Commentator Bob McDonald pointed out, the other heroes are the engineers who designed the miraculous escape capsule which pulled all the trapped men to safety, with no major problems, and ahead of schedule.

We are all engineers; engineers of communication.

May all your engineering projects end as beautifully as the one in Chile.

Information and Other Risky Business

2010-10-11T13:23:00.006-04:00

Those of you who perceive information management as a rather dry affair should examine the strange case of Gabriella Nagy.

Ms. Nagy had a cellphone plan with Rogers. Her husband subscribed to Rogers TV cable service, and decided to add Internet and home phone services. "No problem," said Rogers, who were only too happy to oblige. "In fact, we see that your wife already has a cellphone plan, so to save you money (and make things more efficient), we're going to bundle your cellphone, TV and cable services under one account, and send you one big, juicy consolidated bill!"

Some time later, the husband received the first invoice, which included a detailed listing of all his wife's calls. "That's strange," he noticed while perusing the listing, "there seems to be several rather long phone calls to one number." He called the number, and discovered, much to his dismay, that it belonged to a man who was having an affair with the husband's wife. (The man having the affair was also married.)

After discovering the affair, the husband promptly left his wife, who became so depressed that she lost her job. In May of 2010, she sued Rogers for $600,00 for breach of privacy, claiming that their invoicing process ruined her marriage and destroyed her life.

In informational design and management terms, this occurrence is sometimes referred to as an "oops".

It's hard to know where to begin with all this. On the one hand, Rogers could have taken more care to advise Nagy that her account was about to be consolidated with another, resulting in a shared bill. On the other hand, to blame a communications company for a failed marriage is quite a stretch. Where would the lawsuits end? What about someone who simply uses a cellphone to yell obscenities at another person? Is the cellphone company liable for providing the medium for the message?

This case is similar to one faced by an airline years ago. To promote business, the airline offered a "fly your spouse for free" program. Loving husbands could take their wives on dream vacations, at no extra cost for the second ticket.

The program was quite successful, and being good corporate citizens, the airlines sent thank you letters to all the couples who participated: letters that many of the wives would open (since it was addressed to them and their husband) and read, and who would then wonder aloud: "Gee, I don't remember flying recently with my husband." For it turns out that many husbands did not travel with their wives, but with other assorted female companions.

Oops.

Information development and delivery, much like life, is a balance between security and convenience. The moment you create information, you are also creating risk:

risk that the information is incorrect
risk that the user will not interpret the information correctly
risk that you are exposing the user to information that they should not be exposed to

However, should you decide not to include the information, you are taking another risk: that you have withheld information that the user really did require.

There is no school, no program, and no teacher who can instruct you on how to always strike the right balance. Each instance has to be judged on its merits. Whether Rogers or the wife acted immorally is irrelevant. The fact is they are now both embroiled in a costly and very public legal battle. Many other philandering cellphone users are now quite worried that they will be exposed.

When her family's accounts were bundled, a simple automated email sent to Ms. Nagy could have saved her (and Rogers) much grief:

Dear Ms. Nagy:

Please be advised that your household has requested additional services. These will be bundled under one invoice, which will include a detailed list of your calls. However, if you would like this list to be mailed separately to you, please call us within the next 7 business days so that we can update our mailing records.

(This should keep you out of trouble with your husband as you pursue your illicit affair with your hot lover, whom we have been tracking in real time. However, for a nominal "filtering fee" of only $499, we with withhold this information from your husband.)

Better still, there should have been an opt-in option to have her call details included in the master bill. If no action was taken, the call details list would continue to be sent to her directly.

Yes, Ms. Nagy is ultimately responsible for her downfall. However, Rogers and all those who create and disseminate information also have a responsibility to avoid informational disasters such as these by striking the right balance between disclosing and screening out sensitive information.

TFSA is a four letter word; Gmail is not

2010-09-16T11:15:00.007-04:00

And the winner of the "it seemed like a good idea at the time award" goes to...the Tax Free Savings Account, or TFSA.

The TFSA is a special type of savings account established by the Canadian government, and which came into effect in 2009. Individuals can contribute up to $5,000 per year, and the amount grows tax-free.

Sounds great, right?

Here's the problem: if you contribute $5,000 to your account, withdraw it, and then add it back later, you will get a stiff penalty.

That's right - even though the total balance in your account never exceeded the $5,000 maximum, you will still be penalized.

I know this because it happened to me, along with about 72,000 other taxpayers. (For full details, read my entry on TFSA overcontributions in Wikipedia.)

CRA later admitted the contribution limit rules were confusing, and has said they will allow taxpayers to appeal if they genuinely felt they were mistaken, and that they will review each situation on a case-by-case basis.

The problem was that the entire TFSA programme was inadvertently designed to cause confusion. In other words, failure was built into the system. How?

With many people using online banking, transferring money back and forth between accounts is extremely easy. I, like the 72,000 other hapless taxpayers, simply moved funds back and forth on a regular basis, hoping to get the higher interest rate of the TFSA account.

A warning in small print did appear on the banking website, stating not to exceed the TFSA contribution room. But all that indicated to me and the other users was to not exceed the annual limit. There was no warning indicating that the limit doesn't apply just to the balance but to the total amounts transferred within a year. That difference makes all the difference.

This confusion exposes problems both in usability and documentation. There are several ways it could have been avoided. In order of effectiveness, they are:

1. Clearer documentation should have given to everyone who signed up for a TFSA account. All financial institutions should have emailed, or better yet, phoned, every applicant and clearly explained the transfer limit rules. Even with this warning, though, many people would still have over-contributed. So we move on to the next solution: clearer on-screen warnings.

2. When transferring funds using online banking, a clear warning should have appeared stating that if you transfer more than $5,000 into your TFSA, you will be penalized even if your total TFSA balance is less than $5,000. But again, even with this warning, some people would still have over-contributed, so we move on to the proper solution.

3. The online banking system should have tracked all TFSA transfers and prohibited all transfers that exceeded the overall yearly limit. A message would appear indicating that the transfer would exceed the user's limit, and stating that if they still want to perform the transfer, they would have to phone it in.

This last solution is the only valid one, because it builds success into the system. It prohibits the user from making a really dumb decision, which is what all great software should do. (Of course, it wouldn't prevent overcontributions that occur from one bank to another, but it still would avoid much grief.)

Compare the poorly-designed TFSA with a Gmail's "forgotten attachment" feature. In Gmail, if you prepare an email with the phrase "I've attached", but forget to actually include the attachment, a message appears asking if you still want to send the email without an attachment. Brilliant.

Now, it is not a perfect feature. It won't work if you use the phrase "I attached" or "Check the attached file". Ideally, the feature should just search for the word "attach". But still, it's a fantastic feature because it attempts to build success into the application.

Building success into our documentation means doing everything we can to anticipate how a user will screw up using both the document and the application. It means creating VAD - Value Added Documentation.

VAD does not simply tell the user what they already know, but what they need to know.

For example, a user may want to send a letter to many different people. If the user doesn't know about the mail merge feature, they will insanely copy and paste all the letters.

Having an index entry of mail merge is useless, because if the user doesn't about this feature, they can't look it up! However, having these index entries could help:

distributing a letter to many recipients
letters, sending a letter to many recipients
mailing a letter to many recipients
mass mailings, sending
recipients, sending a letter to
same letter, sending to many recipients
sending a letter to many recipients

Yes, these are long index entries, but so what? A good index attempts to anticipate all the strange and wonderful ways a user might look up a topic.

The mail merge topic itself has to clearly explain why doing a mail merge is better than copying and pasting, because if the user cannot see the benefit of what you are suggesting, they won't do it.

Bottom line - when it comes to bad documentation, don't get mad - get VAD.

A Magically Magical Product that's Full of Magical Magic!

2010-09-02T13:36:00.004-04:00

Apple's a funny entity, somewhere between a corporation and a religion. I'm not a "Mac" person per se, but concede their products are among the few that actual make the news. Other companies would kill to such have constant free publicity. Can you imagine if Chrysler's latest attempt to build a car actually made headlines? It'll be a cold day at the North Pole before that happens.

I also appreciate the beauty, elegance, and extreme usability of their products. My first computer, in fact, was an Apple - an Apple IIc laptop, way back in 1985 - I don't think they even had cars back then.

What a dog the IIc was. It came with a small 9" ugly puke green monochrome screen and had no hard drive - just a built-in 5 1/4 floppy drive. You had to load the software from the floppy each time. The size of the documents was limited to about 9 pages. Still, it was miles ahead of my old typewriter, and did get me through college.

How times have changed. Apple's more recent devices are impressive, from the all-in-one desktops, to their phones, and most recently, the iPad.

I've played around a bit with the iPad and have to admit it's pretty cool. However, I don't like the fact that, unlike a notebook (or smaller netbook), it lays flat; that is, the virtual keyboard is embedded into the screen in one piece, meaning you can't fold it. It's just not ergonomic for me - I like to have the keyboard separate from the monitor and at a right angle to it. But that's just me; millions of other users don't care, as they have actually bought the thing.

Two of the new owners are my parents, who are Mac people. They recently bought an iPad, and asked their techie son to help set it up. I slowly undid the wrapping and beheld its awesome beauty and simplicity. I turn it on, expecting to see the standard desktop I had seen in the store, but instead a most unusual thing appeared - an image of a USB plug and then the word "iTunes".

Huh?

I quickly deduced that the setup procedure involved connecting iPad to the computer, and then opening iTunes. What a waste of good monitor space. Instead of displaying an image and just one word, the iPad startup screen should have given clear instructions:

Connect your iPad to your Apple computer.
Open iTunes.
Follow the setup instructions from the iPad menu in iTunes.

I'm not exactly sure why the iPad doesn't have a separate setup and configuration application, but I guess it's because since iTunes and iPad start with the same letter, Apple felt they should live together.

I proceeded to run an update program to ensure I had the latest version of the "magic". It failed. I tried it again and again it failed. I was taken to a troubleshooting page which listed various solutions, some simple and some about as simple as Japanese mathematics. I thought Apple devices were supposed to make things easier; I certainly wasn't feeling the magic.

Anyway, by a miracle, I was able to restore the iPad to its factory state. I set up a WiFi connection; it worked, but it was so s-l-o-w.

I told my folks to call their "Mac" guy to figure it out.

Apple lovers - I hate those guys....

TWW - Live and In Concert!

2010-08-31T09:31:00.002-04:00

A Tech Writer's World (TWW, a.k.a. me) will be live on stage, sort of.

I'll be the final speaker at the 2010 Toronto STC Career Day, to be held at Seneca@York.

Watch me demonstrate how a resume can be both short and long at the same time, by drawing from the mysterious world of quantum mechanics.

View my notes from this event.

Be there or be triangular!

Censoring the census

2010-07-23T15:07:00.003-04:00

It's a slow month in politics when the current burning issue for the Canadian government is a form document that no-one enjoys completing.

The government is in trouble because of their plans to scrap the mandatory 40-page long version of the census. It would be replaced by a shorter, voluntary version. Opposition parties, statisticians, researchers, and other groups say this will result in unreliable data being collected.

The government argues it's wrong to threaten fines and jail time for failing to fill out the census, and that the long form was too intrusive, with too many personal questions.

The government has a point. Look at some of the information required in the long form census:

the languages you speak at home
your race, nationality, and religion
where you work and how get there
the language you use on the job
how much housework you do
how much time you spend playing with your kids or talking to your parents
whether you have trouble walking, climbing stairs, or bending
who pays the rent or mortgage
how many rooms and bathrooms in your home
whether your home has any "missing or loose floor tiles," "defective steps" or more major deficiencies like "defective plumbing"

Does the government really need all this information? Although it's important for governments to plan for the future, I doubt all these excessive, personal details are really required. But that's not my main complaint.

The real problem is that I don't see why this document (either the long or short version) is even needed.

The entire system of mailing out a paper document to millions of people, having them mail it back, then having thousands of workers manually place the completed forms into a machine that can read them is nonsense.

I'm not suggesting that all this information should just be entered online. Aside from the fact that this assumes everyone has Internet access, this would still be a flawed process because:

it requires people to complete a form, which introduces errors
the data is only entered every few years, meaning it is never up-to-date

The real solution would be to glean the information on a continual basis in real-time from existing government databases. Everyone in Canada already has an ID number: a SIN, or Social Insurance Number. This number already contains much information about you. The government could use this information on a continual basis, in both short and long term planning.

Such a system would actively pull the required information, without forcing citizens to enter it, and would always be current. Yes, it would be an invasion of privacy, but so is the census itself. If you're going to invade everyone's privacy, you might as well do it cheaply and efficiently.

If the government ever created a system, they would simply be following the best practices of modern information management systems. In these systems, manuals are not just issued every few months when there is a release. They are continually updated, regenerated and then posted online. This allows the end user to always have access to the most current version.

It's time to move all paper-based forms to the ash heap of history where they belong.

Census designers - I hate those guys...

Must you be so....human?

2010-07-20T14:10:00.003-04:00

The winner of the technological quote of the year (so far) is:
Just don't hold it that way.

This was Steve Jobs' initial statement when confronted with reception problems of the iPhone 4. He was responding to the now infamous complaint that the signal strength dropped when the phone was held in a typical fashion.

For someone who has built an empire based on outstanding usability, it was an astonishingly stupid thing to say. Jobs was telling his users: we don't need to conform our products to you; instead, you need to confirm to our products. In other words: don't be human.

Jobs' arrogance is not surprising. His string of recent product successes went straight to his already super-sized head. The greatest danger of success is thinking you can do no wrong. After immense pressure, though, he finally relented, offering a free bumper case to fix the problem, and full refunds to users who wanted them.

The simple lesson is this: usability, that is, designing a product with the end user in mind, isn't just one thing - it's every thing. I continually see examples of poor documentation design where the user's needs were an afterthought, if they were a thought at all.

Here are some recent cases:

An investment company sent me some forms to sign. I dutifully signed and returned them all. Later, I received one of the forms back. It turns out that even though it had areas highlighted in yellow for me to sign, date and initial, it was my copy. The only thing indicating this were the tiny words in the bottom right corner stating: Copy 1, Client. Typically, when I receive client copies, they are visibly marked with a stamp or a post-it note, stating: CLIENT COPY - PLEASE RETAIN.

My credit card statement is a spectacular example of wasted space. Each 8 1/2 x 11 page lists only about 20 transactions, which take up about 20% of the page. The information on the remaining 80% (the payment portion, any special news or announcements, the total purchases and balance, and the interest) is unnecessarily duplicated on every page. And the legal information is duplicated on the back of each page! It's not uncommon for my statements to be five or more pages. This isn't just a waste of paper: it makes it harder for me to locate and review all the transactions, because I have so many pages to waft through. The information that only needs to appear once should only appear once. With the space gained, a five-page statement could be reduced to one or two pages. There should also be a line space separating each set of transactions by date, again to make it easier to read through them.

Our garbage pick-up schedule indicated that July 1, the Canada Day holiday, was a pick-up day. Chaos and confusion ruled on our streets. Some people thought this must be a misprint, and did not leave their garbage out. Others took a chance and did take out their garbage. It turns out it was a pickup day, to allow the workmen to enjoy a long weekend. A simple asterisked note on the calender would have avoided all this confusion, for example: Note: This is a collection day despite the official holiday.

Usability must permeate every of your work. It means doing things like:

creating TOCs that can quickly be glanced through to give an aerial view of the product
writing conceptual overviews that leave no doubt about what the object or item in question is, and which include real-world examples and analogies where possible
including overviews in tasks and then explaining the task in simple, easy-to-digest steps
avoiding long sentences and paragraphs
using fonts and page layouts that are clean, simple and readable
breaking up large blocks of text with headings
creating indices that anticipate all the different ways a user could look up a topic

Not doing these things results in unusable documentation. Our response cannot be:
Just don't read it that way.

Our response must be:
Just what is the way you read it?

Join the Bloc!

2010-06-29T14:54:00.012-04:00

Good news: I survived the G20 riots. They happened near my former workplace in downtown Toronto; fortunately, our office had recently moved to the slightly more peaceful city of Markham. No one was surprised by the violence; it was all foreseen, based on the history of previous summits. Remember the "Battle in Seattle" in 1999? It'll be difficult to name this current event, as there are few words that rhyme nicely with Toronto. Perhaps "The Scenario in Ontario".

What exactly did the G20 summit produce? A non-binding document, in which, among other things, the various leaders pledge to reduce their outrageous spending. What happens to leaders who don't meet their deficit reduction targets? Well, the other leaders might stare really, really hard at them, call them names, and maybe even start turning the lights on and off. Oh boy - that'll scare them into fiscal responsibility.

Time for some post-mortem documentation analysis. The security costs alone for the summit were over a billion dollars. There are 10,500 words in the released communiqué. That works out to over $95,000 per word. However, the total cost is even higher when you factor:

transportation, food and housing for all 10,000 delegates
construction of all the venues, including the "fake lake"
the funky G20 logos and marketing
three slightly over-cooked police cars
damages to stores
lost business
court costs for the anarchists

When all these are added in, the cost per word easily exceeds $100,000, a handsome rate for any writer.

Here's a few other random thoughts from this event:

Don't want to be arrested? Read the manual!
Over 900 people were arrested during the summit - a new Toronto record - woo-hoo! Now, some of those arrested and detained were admittedly innocent; passers-by, onlookers and journalists. To avoid future errors, I recommend a Summit Safety Manual be issued to all residents of the next city fortunate enough to host the next G20 summit.

This manual will contain only one procedure:

Not Getting Arrested

If you do not wish to be unavoidably detained and arrested, and held for an unlimited number of hours without access to food, water and washroom facilities, please complete the following task:
Stay far away.

Sign, Sign, Everywhere A Sign
I enjoy reading the communication (a.k.a. signs) displayed by the protesters with such brilliant and pithy statements as:

Ban the G20!
Capitalism sucks!
Bury the bankers!
Nature doesn't do bailouts!

The problem is that unlike a well-written document, the signs don't tell the reader what to do. I therefore plan to show up at the next protest with the following sign:

Ensure your sign includes a clear, specific action for the reader!

Even if the signs had been clearer, as documents they are useless. The world leaders are the end users for these signs. Has there ever been an instance where these leaders have said: "Gee, this sign says 'Ban the G20'. I guess we'd better cancel the meeting." Clearly, the sign-writers have yet to learn the prime directive of technical communication: Know your audience.

A Paradox for Anarchists - Let's Get Organized!
To call the anarchists who destroyed property idiots would be an insult to idiots everywhere. These thugs have the intelligence of blank hard drive. Now, there's nothing wrong with a little bit of revolution now and then; many great nation-states were born from revolution. The difference, of course, is that these historical revolutionaries stood for something, whereas the anarchists stand for nothing, except, of course, more anarchy.

Technical communication is undergoing a revolution from:

traditional WYISWYG tools where the content and the design of information is done simultaneously, and the documents are typically stored locally and organized into chapters and books

to:

server-based XML tools where the author works only with segments of pure text (no formatting), which are classified based on their type and which are stored on a central server that many authors can access

This is a colossal change; I am therefore launching a new movement named after the infamous Black Bloc G20 anarchists - it will be called The Text Bloc.

Join us as we smash old (computer) windows and destroy the old outdated documentation ways!

Chant with me now the following statements:

Death to WYISWYG! (Or at least partial harm to it!)
Paper-based systems don't do bailouts (and they don't do many other things either!)
Hey Mr. C.E.O. - can you spell X.M.L?!
Information wants to be free! (But avoid anthropomorphization!)

The Thrill of "Top Kill"

2010-06-01T10:42:00.000-04:00

British Petroleum (BP), responsible for the worst oil spill in U.S. history, should be given an award. Not for their oil drilling abilities (which one could fairly say are a tad below par), but on their naming abilities.

Specifically, whoever coined the term top kill to describe their latest failed effort to plug the ruptured oil line is a genius. It beautifully and succinctly describes an incredibly complex process.

Technical communicators are often asked to name things, specifically fields and other elements in a user interface. Giving objects clear, simple and self-descriptive names is often quite a challenge.

As an example, several months ago I reviewed the interface of a file migration utility. This application migrates files of one type into another. The interface consists of just one large dialog box. The user enter various parameters, then clicks a button to start the process. The question is: what should the button label be?

Initially, this button was simply labeled Go, but that's not very self-descriptive, is it? Also, Go only has two letters, making the button rather small in stature. The label I suggested, and which was implemented, was: Start migration. It's not as sexy as Top Kill, but it does the job.

Why info systems fail

2010-05-19T16:49:00.005-04:00

If you only have time to read one news article today, read this one from the Financial Post.

Don't leave IT to the techies - Three problems lead to system failures describes in sickening detail the amounts wasted on failed information systems, and the main causes of these failures.

An astounding 68% of information technologies projects fail. This costs the world economy about $6.2-trillion a year. That's about $200,000 a second; imagine all the tech writers you could buy with that.

Here is the most important line in this article: "...failure, in most cases, has little to do with the technology and everything to do with the business process."

Specifically, the three main causes of IT project failure are:

the project manager failing to understand the business requirements
the system's users not being involved in its design
senior management failing to get involved in the project

This is true of any IT project, including any documentation or content management system.

If the documentation manager does not understand the specific business requirements of the proposed system, it will fail.

If the information developers are not involved in choosing or designing a system, or if the system is too difficult to use, it will fail.

If senior management (which can include VPs, CFOs, CIOs or any other alphabet soup) does not support or get involved in the project, it will fail.

It's a cliché but it's true - people don't plan to fail, they fail to plan.

Finally, in the one minute it took you to read this blog entry, another $12 million was wasted...

The PowerPoint from Hell

2010-05-03T16:56:00.010-04:00

General Stanley McChrystal, head of U.S. and NATO forces in Afghanistan, has provided a perfect example of how not to create document: a PowerPoint slide that purports to explain the U.S. military strategy in Afghanistan.

Afghanistan "Explained"

“When we understand that slide, we’ll have won the war,” General McChrystal said. In other words, never. This image is the worst example in history of spaghetti documentation.

Now, compare that monstrosity with a simple document created internationally renowned tax expert Dr. Alvin Rabushka at Stanford University.

The Flat-Tax Postcard

Dr. Rabushka has proposed a 15% flat tax for Canada. This would collect the same amount of revenue that the government currently collects, without having to wade through multi-page, hyper-complicated tax form documents and software.

The good doctor even designed a form the size of a postcard that could be filled out in about five minutes.

It's estimated this simple document could save Canadians $30 billion when you factor in:

the time and effort spent getting receipts and preparing tax returns
the cost to hire accountants and lawyers to sort through the massive tax code
the cost to employ vast armies of tax collectors their support staff

I can think of no two documents with more different content and results.

The PowerPoint explains nothing, saves no money and may even indirectly contribute to the war's endless multi-billion dollar cost by giving the illusion of comprehension to an incomprehensible situation.

The tax form is clear, simple and explicit, and would save billions of dollars.

Which document would you prefer to manage?

A quick tip

2010-05-03T14:49:00.004-04:00

One can discover great technical communication in the unlikeliest of places.

Here's a sample from the bottom portion of a restaurant bill I came across recently:

Gratuity not included

Suggested tip at 15% - 2.10

Suggested tip at 18% - 2.52

Suggested tip at 20% - 2.80

Why oh why did someone not think of this sooner? My only quibble is that the terminology is inconsistent - the heading uses gratuity whereas the listed items use tip, but that's a minor point.

This document saves the user the grief of having to manually calculate the tip. It considers the needs of the user and immediately fulfills them, like any great document should.

The Tech Writer vs. The Volcano

2010-04-28T11:47:00.001-04:00

After a week of chaos-inducing activity, the volcano in Iceland finally ran out steam, or in this case, lava and smoke. If a mountain could be arrested for causing a public disturbance, surely this one would qualify.

Fortunately in our profession, we don't have to battle lava and smoke. However, we often have to clean up a mess. As smoke and ash cloud the air making it hard to see what's out there, so do confusion, apathy and vagueness cloud up a document.

One of my company's current projects is to rewrite an enormous documentation set. Some of the guides are several years old, and it shows. The documents were not always maintained, fogging up the truth, and hiding the important facts users need to know.

I am not certain of what would be the easier task: fixing the doc set, or getting a volcano to stop exploding.

Time will decide.

The Mother of all Engineering Feats

2010-04-21T16:26:00.003-04:00

British scientists were able to create human embryos with genetic material from one man and two women. The goal is to produce genetically altered "designer" babies and thereby eliminate hereditary diseases by combining the best bits of each person. It's a controversial idea, but if saves lives and improves health, I'm all for it. Plus, you'd get to tell all your friends you have three parents - how cool is that?

Just as people have genetic strengths and weaknesses, so do technical communicators have strengths and weaknesses in their profession. Strengths in technical communicators include:

being friendly and outgoing
able to work quietly in solitude
able to work with a wide variety of people
able to work with like-minded people
a solid language background
a solid technical background
excellent written communication skills
excellent oral communication skills
able to see "the big picture"
an eye for detail
able to work in chaos
are comfortable with routine
able to follow existing standards
able to create new standards
able to view information textually
able to view information graphically
valuing simplicity over complexity
valuing completeness over simplicity
enjoy starting new projects
enjoy updating existing projects
able to work well with WYISWYG tools
able to work well with non-WYISWYG tools

As should be obvious, no single technical writer could possibly have all these strengths, because many of them contradict each other. The best documentation teams, therefore, have a good mix of writers from a variety of backgrounds.

I was once asked in a job interview this intriguing question:
Who would make the better technical writer?
a) Someone who studied language and writing, and then later learned technical skills
or
b) Someone who studied technical information, and then later learned language and writing?

The short answer is - we can't know. The longer answer is: it depends what you mean by "better technical writer". Either person may match the requirements of a particular job, and it is impossible to know from these brief descriptions who is the more apt candidate.

For example, I remember looking through medical textbooks a few years ago. They contain detailed pictures of human anatomy. Only two types of technical communicators could have created these images:

a) a graphic artist who learned anatomy
or
b) a medical person who learned art

There is no way to tell by looking at the illustrations which of these two communicators were responsible.

You can never be all things to all companies. You cannot be "the perfect writer", however, you can be perfect for a particular job. You have a complex set of skills and traits - you "tech comm DNA". Know your DNA, and you will know where you should be and what should be doing.

Inspired by truth

2010-04-15T16:42:00.003-04:00

Inspired by true events is a tag line appearing in some new films. This slogan replaced the previous antiquated version: Based on a true story. It is also complete nonsense, because all films, indeed all art, is "inspired" by true events, because all art is inspiration from actual life.

This is a classic example of marketers taking a perfectly good piece of text and ruining it with meaningless gray words so as not to offend anyone. I enjoy fictional works as much as anyone, but please don't mix my fact and fiction. I would rather see a documentary than an artistic film claiming to be "inspired by true events", because in a documentary, I'd assume everything I see actually happened. In the "inspired" film, I wouldn't be so sure.

There are writers, and then there are technical writers, and never the 'twain shall meet. Technical writing is as different from fictional writing as house painting is from artistic painting. Writing a novel does not qualify a person to be a technical writer. It only qualifies them to be a story-teller.

We don't tell stories. We don't spin yarns or tell tales. We explain the facts; the what, where, when, why and how. We don't get into feelings or characters. We remain cool and unemotional in our work. You may try to change us to novelists and ad men, but you will fail.

We are logical. We battle confusion and uncertainty.

We are Vulcan. We are the Borg.

Resistance is futile.

The Big Bang of Information

2010-04-08T12:18:00.005-04:00

Scientists are edging ever closer to discovering the deepest mysteries of the universe. The world's largest particle accelerator, a monster of a machine with a circumference of 27 km, is now online. Named the Large Hadron Collider, this machine is so big it occupies two countries: Switzerland and France.

This accelerator smashes sub-atomic particles into each another at speeds approaching that of light, creating collisions of almost 14 trillion electron volts. (Almost enough to power Windows 7.) In doing so, scientists hope to recreate the conditions that existed immediately after the Big Bang, when the universe exploded into existence.

One popular misconception about the Big Bang is that it was an explosion of matter into space. In fact, it was an explosion of space itself. That is, space itself expanded, and continues to expand, into nothing. Now, it's very hard to define nothing; one can only say it is the opposite of something.

There was some concern that the accelerator might actually create a black hole, and swallow up our galaxy. If that happens, I may have to suspend this blog for a while. Black holes notwithstanding, the Large Hadron Collider could prove the existence of the Higgs boson, also know as the "God particle." If this particle can be recreated, it would have enormous cosmological implications, because it would prove the Standard Model theory of the universe, a theory that explains how all matter and energy are connected.

So, we have never been as close to the Big Bang as we are now. However, space is not the only thing that's been exploding: so has information. There's probably more information produced today in one second than was produced in a hundred years just a few centuries ago. Think of all the places information exists:

the Internet
computers
bookstores
signs
stickers
personal letters and documents
companies
governments
that big mess in the back of your closet

Billions and billions of pages, and it keeps growing like a monster. Soon even the universe won't be big enough to hold it all.

Information has exploded as rapidly as the universe. But if the universe began as tiny particle, did all the world's information begin as one? And, if so, how could we represent that?

We could start with the word itself: information. But this word can be further compressed and expressed simply as the letter i, the international symbol for information. [i] signs are visible at airports and other public places. People intuitively know that [i] = information.

In addition, i has two parts: a short upward line with a small dot on top of it. The line is an arrow, directing you to a dot. The dot is the point, literally. If your document does not make the necessary points, it has no point, and it is not useful information, but dark matter.

All information, therefore, began from the lowly i.

The i tells all.

The i is infinite.

The i is the i-ching of our profession.

3D Documentation

2010-04-07T21:00:00.001-04:00

I recently experienced the latest technological marvel: 3D television, and have to admit - it is spectacular. The images have an incredible depth, and also can appear to "pop out" towards you, for a virtual virtual reality experience. But it ain't a cheap experience.

A 40" Samsung 3D TV currently sells for $2,500 CDN. The special glasses required sell for $250 a pair. For a typical family of four, that means an extra $1,000 just for the eyewear! And, you have to buy a new Blu-Ray player and new 3D Blu-Ray disks. And a new type of cable to connect it all. Didn't we just go from DVD to Blu-Ray? What's next? 4D TV?

To be fair, 3D TVs can also convert regular 2D images (regular TV channels and DVDs) to 3D, but the effect is not as great as with a true 3D source. If nothing else, 3D TV will drive down the price of regular HDTVs, which themselves are light years ahead of CRT TVs.

The price will have to drop considerably for this new technology to have any chance of succeeding. If it does, it is proof that people are willing to spend just to get an extra dimension. However, dimensions don't just apply to images: they also apply to information.

The dimension of information is its scope and quality. If the contents of a guide have a good dimension to them, it means they are in-depth, clear, detailed, meaningful and practical. If the contents lack dimension, then the guide is "flat". A flat guide explains only the basic facts of a product, and not their relevance or practical application. A flat guide does not add value; a dimensional guide is the essence of "value-added".

Adding dimension to a guide means including things such as:

clear explanations of all the concepts
a detailed glossary of all the terms; if a term is used in the definition of another term, it should be hyperlinked to its definition so the user can easily move from one term to the next
an explanation of exactly why a user would complete a task, before presenting the actual task steps; if the explanation itself raises another "why?", then it is not a true explanation
different ways to accomplish the same task
relevant cross-references to other topics (but not too many because then the user will be overwhelmed!)
detailed screenshots, with all of the elements clearly labeled
a rich index that anticipates all the ways a user might look up a topic
a feedback form where users can directly comment on the usefulness of a topic

Don't be flat. Take your docs into the next dimension. (No 3D glasses required.)

A healthy-sized document

2010-03-31T15:23:00.006-04:00

The Obama administration scored a major victory with the passage of its health care bill, a massive 2,000+ page document . I wonder if every Senator and Congressman has actually read the entire thing; a Quick Start Guide would be useful.

This bill sounds great in theory: millions of Americans who were not previously insured now will be. Insurance companies can no longer exclude people with pre-existing conditions, which from the horror stories I've heard could include symptoms such as "breathing" and "blinking". Time will tell, though, if this bill will actually save lives. However, a new television show offers an enlightening perspective.

Jamie Oliver is a English celebrity chef who advocates healthy eating. He's exposed and improved the quality of meals served in the English school system. In his latest show, Jamie Oliver's Food Revolution, he visits Huntington, West Virginia, ranked as one of the the least healthy cities in the U.S. He is shocked to discover the high-sugar and high-fat processed junk being fed to schoolchildren twice each day.

Two scenes from this show will be forever etched in my memory. One is an experiment with some of the schoolchildren that goes horribly wrong. Jamie brings several young children into his kitchen-storefront. He takes out a chicken and shows them the good cuts of meat from it - the breasts, the thighs, and so on. What remains is the disgusting garbage leftover - the bones, cartilage and fat. He places these horrid leftovers into a blender, liquifies them, and adds artificial flavours and fillers, makes them into patties and deep fries them, to demonstrate how chicken nuggets are actually made.

At this point, Jamie asks the children if they would like to eat these nuggets, fully expecting that none of them will. To his shock, the children ask to eat them! Why? Because they are hungry.

In an even more disturbing segment, Jamie visits a classroom. He discovers that the children cannot identify basic vegetables such as tomatoes, potatoes and cauliflower. They can identify ketchup, french fries and hamburgers but have no idea as to where these items come from. In a later follow-up visit, the children have learned to identify the vegetables, but I've no doubt that this ignorance is common throughout the country.

Returning to the health care bill - the problem is that this bill does not directly address what is really killing and maiming Americans by the millions: poor diet, lack of exercise, and mental health issues including addictions such as smoking and drinking. This bill treats the symptoms of poor health, not the major causes or reasons.

It's important to be aware of symptoms vs. underlying reasons in our profession. It's a common perception that the purpose of technical communication is to instruct users on how to use a product or service. Although this is true, it is not the true reason, for we can always ask: Why do companies care if their clients can use the product? They care because if users can't use the product, they will either return it or call tech support, both of which drain profits. However, even that is not the true reason.

For the true reason, we need to understand that all belief systems have definitions of good and evil. In the free-market capitalist system, the definitions are:

good – anything that increases profits
evil – anything that decreases profits

Now we have the real reason, and not the "symptom" behind the need for technical communication. It's not to tell users how to use products, or to lower support costs, even though both these things are important. It is to maximize profits.

This is also the true reason because we cannot effectively ask "Why do companies need to maximize profits?" They just do.

Remember this in an interview. Technical communicators already are a disadvantaged minority, because we are a cost centre and not a revenue generator. Therefore, in a interview, you must show how you increased profits by decreasing costs.

Be good; don't be evil.

Size doesn't matter

2010-03-28T10:19:00.004-04:00

The Canadian government recently released over 2,500 pages of documentation. This was in response to pressure from the opposition parties regarding the controversy over how Afghan detainees were treated by the Canadian military.

2,500 pages sounds like a huge amount. The problem is that most of it was censored for "security" reasons, an explanation which the opposition, of course, does not accept. My first reaction when I saw the heavily-blacked out copies on the news was that it was a huge waste of toner and paper. The government could have spared themselves much grief, ink and trees if they had simply emailed everyone a document that only contained the non-redacted text.

Tech writers often get hung up size. Picture this conversation:

Tech Writer A: I'm working on a guide that's 300 pages!

Tech Writer B: That's nothing - I'm working on a guide that's 1,000 pages!

Tech Writer C: 1,000 pages? That's a lot - if you're a little girl...

Size just doesn't matter. The quality of a document is not proportional to its volume. Some shorter documents are useful while other larger ones are not. In fact, less is often more. Succinctness and brevity while remaining clear and thorough are the true hallmarks of quality.

No sex please, I'm neutral

2010-03-18T13:40:00.003-04:00

In an extreme version of single-sourcing, Australian officials issued an immigration certificate with the Gender field listed as not specified.

The document was issued to immigrant Norrie May-Welby, who was born a man but later had a sex change operation. The procedure included taking female hormones, but after several years, this person stopped taking the medicine and decided to become a "gender-neutral". "The concepts of man or woman don't fit me," he said.

Oops - I mean she said... I mean s/he said. (Damn these restrictive pronouns!)

A few points on this rather delicate topic.

1. Do the sex and gender fields of all government forms need to be revised to include "none of the above"?

2. If this answer to the above is "no", how does one handle rare documentation cases such as these?

Technical communication ideally is as digital as the computer file itself. That is, every topic, concept, state and procedure is clearly defined with no ambiguities. True or false. 1 or 0. Binary or death.

Now, the best way to avoid confusion is to explicitly define your terms. All objects, actions and items must be clearly described using non-technical words which themselves need no further definition or explanation. Otherwise you end up with sentences like this:

To folicate the nefigog, you need to parrelify the actrawan.

Unfortunately, uncertainties and confusion sometimes occur. Or to put it more succinctly - sh-t happens. What then?

It all depends on the dreaded probability factor, which is:

A. the number of users who may encounter this situation
times
B. the number of times they might experience it

If this factor is high, then it indicates a flaw in the design of the product itself. If the usability and repair budgets are exhausted, and there will be no fix forthcoming, it falls upon the shoulders of the lowly technical communicator to openly document this heinous behaviour, probably in a number of places, for example: the ReadMe, the User Guide, the Install Guide, and so on.

If this factor is low, the exception can still be documented, but less frequently. For example, in the aforementioned "gender neutral" problem, given the few times this will occur, I would add a brief note to the field description, something like:

Select a Gender: M for Male, F for Female, O for Other.

Note: If you select Other, you can enter more detailed description, because we're really curious to know just what the hell you are.

When mail merges go bad

2010-03-18T13:16:00.004-04:00

697 former Parliament employees received a T4 tax form that belonged to somebody else.

Government House leader Jay Hill said the mixup probably happened when the employee lists were incorrectly merged with other addresses.

Responding to this documentation crisis, here is Mr. Hill's quote of the day:

"I often wonder when people sit and stare at these computer screens all day why there aren't a lot more errors like this."

Time to take a break from this screen, I think.

Blockbusted

2010-03-18T13:01:00.004-04:00

Blockbuster Video is going bust. Although they have not officially filed for bankruptcy, it seems certain they will soon have no choice. This comes as no surprise, of course. The very idea of driving to a store to rent a movie is as outdated as a typewriter or Windows 3.1.

People today get their movies through mail rental services, downloading (legal and otherwise), video on demand and even vending machines. The funny thing is that Blockbuster offers these alternate services, yet is still going broke. Why? Because most of its customers are simply not aware of these services, allowing other companies to corner the market.

Lack of awareness is a big problem for our profession. Users don't know how to use products because the users are unaware. If helpful documentation is available, users don't know it. If users do know that documentation is available, they don't know how to find it. If users can find it, they don't know how to effectively use it. And even if the users do know how to use the document, the document itself may lack awareness if it does not clearly explain what the user is looking for.

As a result of all this ignorance, many working products are returned to stores because the users could not figure them out. The goal, therefore, should be to create visible, usable documentation. Otherwise, you will get busted.

Security breach!

2010-03-11T13:25:00.009-05:00

It's always entertaining to read about non-lethal lapses in security at a major event. Remember the debacle at the 2010 Winter Olympics? A man with false ID got within a few yards of U.S. Vice President Joe Biden before being arrested at the opening ceremony. You'd figure after spending almost a billion dollars on security, the organizers would be able to hire people who could spot phony passes. (I also wonder if the intruder got a refund, because, hey, opening ceremony tickets are expensive!)

Another security breach also involved the White House, where an uninvited couple crashed a State dinner, and actually met the President and Vice President. Security officials admitted there was a breach but said not to worry; the couple didn't have any weapons. Gee, that's a relief...

These incidents are actually symptoms of a much larger debate: balancing security with democracy. This has been a problem for society long before terrorists or 9-11, however modern terrorism has made the balancing act much more difficult.

On the one hand, governments have a responsibility to stop attacks and ensure their citizens are protected. On the other hand, they have to ensure they don't turn their nations into police states.

On a more personal level, regular people face the "security vs. freedom" question. Having a credit card is convenient, but can expose you to fraud. Driving a car gives you mobility, but you run the risk of death or dismemberment. Every day, we're always making trade-offs between safety and convenience.

Technical communicators are no different. One of the most difficult tasks in our profession is deciding what information to give to users, and what to withhold. Make no mistake - it is often in the user's best interest not to tell them everything possible about the product you are documenting.

For example, you may be documenting a web-based product which has a particular task that can be reversed or "undone". However, you may want to withhold that information, because by telling the user they can "undo" one function, they may assume they can undo other tasks, leading to disaster.

Another example relates to FrameMaker. If I were documenting this product, I would probably not tell users that they can:

combine conditional text conditions
include text insets within insets

because either of these actions actually creates further problems.

However, there is something much more valuable that the security debate teaches us: the importance of proper information gathering. 9-11 was a failure to properly gather, consolidate and evaluate information. The right questions were not asked of the right people.

Contrast that failure with how an Israeli security agent questioned Ann-Marie Doreen Murphy, a 32 year-old Irish woman who was trying to board an El Al flight to Jerusalem in 1986.

The conversation went something like this:

Agent: Did you pack your bags yourself?

Murphy: No.

Agent: What is the purpose of your trip to Israel?

Murphy: For a vacation.

Agent: Are you married?

Murphy: No.

Agent: Traveling alone?

Murphy: Yes.

Agent: Is this your first trip abroad?

Murphy: Yes.

Agent: Do you have relatives in Israel?

Murphy: No.

Agent: Are you going to meet someone in Israel?

Murphy: No.

Agent: Has your vacation been planned for a long time?

Murphy: No.

Agent: Where will you stay while you’re in Israel?

Murphy: The Tel Aviv Hilton.

Agent: How much money do you have with you?

Agent: Fifty pounds.
(Note: This is less than what a single night at the Hilton cost.)

Agent: Do you have a credit card?

Murphy: Yes.

However, she did not; instead, she showed the agent an ID for cashing cheques.

The agent sent her bag for additional inspection. A bomb was discovered hidden in her bag. Her lover had planted the bomb, unbeknowst to her. (Something tells me they're probably not still a couple.)

Note that the bomb was discovered without any technical devices or sophisticated electronics . The agent simply used proper interviewing and behavioural observational techniques to discover the truth.

This is precisely what technical communicators need to do. Fancy documentation tools are nice, but they are no substitute for intelligent investigation.

When researching a document, you may have a conversation like this with a SME:

Writer: Is X true?
(where X is any statement of fact about the product you are trying to document)

SME: Oh yes, absolutely X is true.

Writer: Is it true all the time and under all circumstances?
SME: Uh yes, I think so. I'm pretty sure it is.

Writer: Well, what about in situation Y, or if you were to do task Z to get to X?
SME: Actually, in those cases, X is not true.

Writer: Thank you.

This happens all the time. It's not that SMEs are stupid or don't want us to do our jobs - it's that they are trapped in their world of code and are often not able to see beyond it. They often lack the holistic, big-picture view that technical communicators must have in order to successfully document a product.

People who are studying technical communication in school should also take courses in detective work and investigative journalism, because all tech writers are really detectives and reporters.

Taxing my docs

2010-03-03T13:18:00.003-05:00

I recently attended an STC conference where one of the topics discussed was user-centred design. I met with usability experts and interaction designers whose sole job is ensuring that a product is intuitive and easy to use from a user's perspective, and not from the business's.

At the conference, I met someone who visited Intuit's usability lab in California. It's a multi-million dollar facility where they exhaustively test usability, bringing in many different typical users of their products. You can see the results in their software: TurboTax in the U.S. and QuickTax in Canada. I have QuickTax and I can say it is one of the most well-designed, user friendly and intuitive products I have ever seen.

So, if you want to create well-designed, user-centric documents, then study, use, and analyze well-designed, user-centric products. For in the end, the document is as much a product as the product itself.

The Sixth Sense

2010-03-03T12:37:00.006-05:00

We all know (and love) our five senses: sight, hearing, taste, smell, and touch. Apparently, these senses are not enough. Science, psychology, and the arts have been on the hunt for a sixth sense since the time people knew they had senses.

Candidates for a sixth sense include:

intuition
emotion
intelligence
extra-sensory perception (ESP)
equilibrioception - the ability to balance

As a technical person, one of the candidates that I find particularly interesting is a device called, (what else?), the SixthSense.

The SixthSense is prototype information device you can wear. It consists of a computer, a pocket projector, a mirror, and a camera. The projector projects visual information onto any surface. The user wears colored markers on their fingertips. The camera recognizes and tracks the user's hand gestures, kind of like in the film Minority Report.

There are many cool things that you can do with this device just by using your hands to virtually "draw" various shapes:

"draw" a magnifying glass to launch a map application
"draw" virtual shapes onto any surface
"draw" a frame to launch the camera
"draw" the ‘@’ symbol to check your email
"draw" a circle on your wrist to project a watch onto it
use hand gestures to flick through photos you've taken

Most importantly, SixthSense can detect different types of physical objects and then project additional, meaningful information onto them.

Examples include projecting:

live video news or dynamic news updates onto a newspaper
current airline departure information onto an airline ticket.
nutritional information and recipes onto food packages you are looking at the supermarket
book reviews onto a book
a person's favourite websites onto the person's shirt (yes, it really can do that!)

This device is a glimpse of a future world awash in meta-information. It is currently a prototype, and not freely available. However, the documentation we create is. For this, there are valuable lessons.

First - all technical communicators do have a sixth sense - the sense of information. And not just any information, but clear and meaningful information. We know, or can find out, what the user needs to know. We know how to give that information to the user. The only thing we don't know is what what we don't know. But we know that we don't know what we don't know, you know?

To find out what we don't know, we speak with the people who do know. These are the other people involved with the product you are documenting. Particularly important are the people who are working with the users who actually use the product. These are the salesmen, product analysts, business analysts and others who have direct contact with the end users.

Second - our documentation should be as helpful as a SixthSense device. It should:

"know" the user
know what the user needs to know
give them the information they need to know
tell them how to get more or different information
withhold information they do not need to know

Do you agree? If not, I'm not worried.

You'll come to your senses...

Gold, finally

2010-03-03T12:25:00.005-05:00

I admit I'm not a huge hockey fan. For me, the ability to insert a small, black plastic cylinder into a mesh just doesn't give me a warm fuzzy. However, even I have to admit it is remarkable that Canada won gold in both the men's and women's hockey at the Vancouver 2010 Olympics.

I agree it is somewhat sexist that Canadians have been focusing more on the men's win than the women's. Maybe it's because the score was so close. I think it's because the Canadian men's team lost to the same opponent (the U.S.) only a few days before.

Now, I admit I'm not a sports analyst (just a lowly information analyst), but I would say the Canadians won because they learned from the mistakes they made in the first game. The Americans, on the other hand, because they did not fail at the first game, had no mistakes to learn from.

Mistakes, therefore, are quite important. Before a draft is finally unleashed upon your readers, make as many bloody mistakes as you can; real nasty ones, if possible. Typos. Missing headings. Confusing overviews. Font failures. Awful grammar. Procedures missing steps. The more, the merrier.

Learn from your mistakes. Find them. Fix them. Then, when the software goes "gold", so too will your draft become golden.

Krazy Karl Rabeder

2010-03-03T12:20:00.000-05:00

Karl Rabeder is an Austrian millionaire. But he's sad - so sad that he's giving away his entire $5 million fortune, to charity.

"My idea is to have nothing left. Absolutely nothing," he said. "Money is counterproductive --it prevents happiness."

Karl continues: "For a long time I believed that more wealth and luxury automatically meant more happiness," he said. "I come from a very poor family where the rules were to work more to achieve more material things, and I applied this for many years."

Later in life, his views changed. "More and more I heard the words, 'Stop what you are doing now -- all this luxury and consumerism -- and start your real life'," he said. "I had the feeling I was working as a slave for things that I did not wish for or need...I was just listening to the voice of my heart and soul."

So, he has moved out of his mansion into a small hut. I wonder Mrs. Rabeder thinks of her new home.

If Karl's move is successful, he should write a user guide describing the process: The Millionaire's Guide to Living Poor. It could cover such topics as:

Filth is Your Friend
How To Eat Almost Anything
Got Mud and Straw? Let's Start Building A Home!
Saying Goodbye to Your 55" TV
Convincing Your Family that Poverty Builds Character (yeah, right)

I sympathize with Karl. Feeling sad sometimes is completely normal. I'm just not sure the solution is to become a hobo.

We're often challenged by our docs. A draft review comes back, and it ain't pretty. That doesn't mean we have failed; on the contrary. The only thing worse than a draft full of revisions is a draft with none. Mistakes and omissions are important; from them we grow into better technical communicators.

It's also important to remember that the end user never sees all the changes, heated discussions, endless debates and other nonsense that occurs when a document is being developed. All they see is the final product. They don't know, nor do they care, about how it got there, just that it's good now.

Think about it - do you care about all the errors that were made before you got your hands on a product you were using? Whether it's a TV, a chair or a pair of shoes, all you care about is that the errors were resolved. Especially if you own a Toyota.

So, if work's getting you down, don't quit, and don't move into a hut. Savour the challenges. For when you hammer steel, it becomes harder.

A New Mantra

2010-03-02T19:10:00.000-05:00

Apple has given technical communicators a new mantra.

The Apple slogan is: There's an app for that, to market the fact they have an app for everything and then some, for their ubiquitous iPod touch and iPhones.

Our new slogan should be: There's a doc for that, to market the fact that we can create a document for anything.

Driving a car?
There's a doc for that.

Assembling a table?
There's a doc for that.

Launching the space shuttle?
There's a whole bunch of docs for that.

I'm sorry

2010-02-20T15:44:00.007-05:00

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.

Wall Street Journal - Free My Info!

2010-02-16T17:00:00.005-05:00

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.

The Chilean Mother of All Typos

2010-02-16T16:47:00.004-05:00

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.

Olympian glitches

2010-02-16T16:04:00.009-05:00

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.

And the Oscar goes to...

2010-02-07T13:20:00.008-05:00

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.

Recalling all recalls

2010-02-05T16:41:00.010-05:00

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

Colour my worries away...

2010-02-01T11:45:00.004-05:00

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.

Collaborative editing 101

2010-01-08T16:20:00.002-05:00

Check out this great example of online collaborative editing using Google docs.

It's a video of a group of friends editing a document.

Watch it, then watch it again, pausing to see the changes.

Compare the original, long-winded, version with the much simpler, and much better final version.

Ain't technology grand?

An Echo from History

2009-12-31T10:49:00.013-05:00

One of Sting's finest songs is Children's Crusade - his haunting lament on the follies of war, specifically, the First World War.

Here are the relevant lyrics:

Young men, and soldiers, Nineteen Fourteen
Marching through countries they'd never seen
Virgins with rifles, a game of charades
All for a Children's Crusade

Pawns in the game are not victims of chance
Strewn on the fields of Belgium and France
Poppies for young men, death's bitter trade
All of those young lives betrayed

The children of England would never be slaves
They're trapped on the wire and dying in waves
The flower of England face down in the mud
And stained in the blood of a whole generation

Corpulent generals safe behind lines
History's lessons drowned in red wine
Poppies for young men, death's bitter trade
All of those young lives betrayed
All for a Children's Crusade

This wonderful and majestic piece sounds as fresh today as it did when it was released 25 years ago in 1985. (Wow, has it been that long?)

Although more people died in the Second World War than the first, in many ways, the First World War was more horrible because of the sheer senselessness in the way it was fought. Hundreds (and sometimes thousands) of men would be killed just to gain a few feet of ground, which would often be lost the next day. There was no concept of modern warfare - it was often just organized chaos.

One of the Canadian soldiers who fought in the First World War was Fred Albright, a prominent young lawyer from Calgary, Alberta. He met a woman named Evelyn and they began writing each other quite frequently. They married in 1914; three years later Fred was killed at the battle of Passchendaele.

Their correspondence both before and during their marriage represents an enormous volume of personal documentation. Together, they wrote over 550 letters covering a wide range of topics. Even after Fred died, Evelyn continued to write him in a effort to deal with her grief.

This incredible glimpse into history would have been lost forever but for the efforts of a library assistant who discovered the letters while working at the Archives and Research Collections Centre in the D.B. Weldon Library at the University of Western Ontario. Fascinated by the letters, she painstakingly transcribed and edited their contents so that they could be posted to a website entitled: An Echo in My Heart.

By the way, the assistant is my mother.

You may go back in time here....

Resolve this

2009-12-22T09:51:00.012-05:00

My new year's resolutions all involve documentation, of course.

The Paper Chase

My first resolution is to organize all the various printed guides, warranties, and other paper documents that have accumulated over the years and randomly spread themselves into various piles throughout my home.

I will review each and every paper item and discard what I don't need. (I hate paper and wish we lived in a paper-free Star Trek world.) The relevant leftovers will be grouped and placed into large envelopes and stored alphabetically in a box.

My extensive printed documentation collection includes the following:

big electronics - TVs, Blu-Ray and DVD disc players, CD player, home theatre and satellite receiver, gaming unit
little electronics - MP3 players, cameras, phones, remotes, clocks, shavers, hardware tools, watches, electric toothbrush, organic mind reader
main computer items - user guides, and guides for the motherboard, DVD burner, RAM
peripheral computer items - mouse, monitor, keyboard, speakers, scanner, Webcam, backup drive, software documentation, USB powered teleporter
kitchen appliances - fridge, stove, microwave, dishwasher, blender, toaster oven, indoor spit
garage items - snowblower, lawnmower, trimmer, BBQ, Ferrari guide
miscellaneous items - washer and dryer, vacuum cleaners, non-electric items such as board games, hot water heater, humidifier, kitchen faucet, Sherman tank

(God, I have a lot of crap.)

Soft Sell

My second resolution is to conduct a complete audit of all the soft documents on my computer and again, get rid of what I don't need and keep the good stuff. There's many documents that are several years old that I never read and know I'll never need. Other documents need to be rewritten, merged or reclassified.

Onward and Online

My final resolution, a continuation of the second, is to move as many of my files online as possible. As long as the document does not contain sensitive or critical financial information (like my Swiss bank account number and Tiger Woods' cell phone number), I will move it to Google docs.

In addition to textual documents, my most precious files are my photographs. Before the era of digital photography, people took pictures with something called a film camera, which produced something called prints. I have hundreds of these prints in special books called photo albums. They are single copies only - there is no backup. My long term goal, therefore, is to scan every one of these photographs and upload them to private albums on Flickr.

Managing Catastrophe

I have heard of too many cases where hard drives have failed and people have lost all their files. Backups help with this problem, but if your house burns down or is burglarized, they have no value. The ideal state to be in if you lost your hard drive for any reason would be that you simply buy another computer, connect to the Internet, and access all your files.

Confidential files should be whittled down to a size that can fit on a USB key. That key should then be kept at a location away from your computer. Alternatively, you can use an online backup site. ADrive, for example, gives you 50 GB of free online storage.

Is this ringing any (alarm) bells?

If any of these documentation issues sound familiar (a plethora of printed docs, unorganized soft docs, and lack of an off-site backup for your documents and photos), welcome to the club. Most people simply don't make the effort to deal with these ongoing doc issues.

However, we technical communicators are not most people - we are the Communicati - the enlightened communication and documentation high priests. If we fail to maintain our own documentation, what chance do normal folk have?

The draft from Copenhagen

2009-12-21T16:31:00.011-05:00

Let me see if got this straight: hundreds of leaders, civil servants, and NGOs gathered from all over the world in Copenhagen to address the problem of global warming.

They flew in using private jets, were driven around in gasoline-guzzling limousines, and ate gourmet food flown in from hundreds of kilometers away in order to create an accord that would deal with the excessive use of our limited resources.

Millions of dollars were spent hosting the summit. Enormous effort was expended in the countless meetings and negotiations.

The final result?

A three-page, non-legally binding document that has no long-term targets for cutting greenhouse gas emissions.

Even if this document were binding and had targets, given the political and economic realities of the time (i.e., governments don't want their citizens rioting due to lack of work), it is extremely doubtful this accord would actually have been implemented. (Do any countries actually follow the Kyoto accord?)

Never before has so much money, time, and effort been spent to produce such a thin document of so little value.

Actually, it's a wonder that even this document was produced. Given how difficult it is to get consensus on a simple user guide, giving two weeks for 120 of the world's leaders to agree on a document that could change the world is an impossible task.

It's like trying to write every software guide that has ever been written from scratch...

...in a one-week period...

...using only two tech writers.

Just watch me

2009-12-21T16:20:00.003-05:00

I bought a new watch recently - digital, of course; I don't do analogue.

It's a watch only a tech writer could love: the day, date and time are clearly visible with massive fonts on a over-sized display.

Imagine my disappointment when after taking it home, I discovered the wrong user guide had been included. I tried to find the guide online, but, incredibly, it was not available on the manufacturer's website. (Fortunately, I was able to figure out how to set the time.)

So many user guides; so few tech writers to get them online.