A Transcendent Man

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:

1. The line between people and machines will blur as machines become more human and humans add more technology to their bodies.
2. Machines will grow to be billions of times more intelligent than they currently are.
3. Machines will eventually become smarter than people in a history-shattering event called The Singularity. 
4. 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).
5. Computers the size of planets will be built; Earth itself will be transformed into a giant computer.
6. 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...

Read More

A Relatively Unique Document

(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

Read More

Another Relatively Unique Document

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.

Read More

A Technical Communication Occupation

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:

1. 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.
2. 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%?

Read More

A Note on the New Notes

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.

Read More

How do you like them Apples?

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.

Read More

I Can C Clearly Now

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.

Read More

reCAPTCHA'd!

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:

1. When a document is scanned, it detects a word that it cannot convert. Let's call this the "unknown word".
2. The reCAPTCHA process sends this unknown word as a CAPTCHA for people to deciphere.
3. The CAPTCHA contains not only the "unknown word", but another word which the system already knows. We'll call this the "known word".
4. In the CATPCHA that is created, the user is asked to read both words and enter them.
5. If the user solves the known word, the system assumes that their answer will be correct for the unknown word.
6. The system also gives the unknown word to a few other people to verify that the original answer was correct.
7. 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.
8. 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:

1. Is there a better way to present this information to the end user?
2. What else would a user need to know about this concept, task, or thing?
3. How does the user use our documents?
4. 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.

Read More

The Dynamic Blogger

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.

Read More

The Art of the White Night

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?

Read More

Here kitty, kitty (or maybe not)

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.

Read More

Netflix My Net-Docs

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

Read More

Shaken

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

Read More

A Lasting Theorem

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:

1. Topics (such as overviews or procedures) that answer specific questions.
2. Containers and sub-containers for the various topics (such as other topics, pages, chapters or other sections).
3. A function enabling the user to search the topics (an index, TOC, or content search function).
4. 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:

1. 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?"
2. The process of determining where to find the answers.
3. Locating the relevant information repository.
4. Searching the information repository.
5. Locating the topic that they hope will answer their question.
6. Understanding the answer to their question, that is, the contents of the relevant topic.
7. 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:

1. Consider all the potential questions a user could have.
2. Create topics that successfully resolve these questions.
3. Ensure the topics are written so that the user will understand them.
4. Index the topics so that they are searchable.
5. Create a search system that will enable the user to find the relevant topic.
6. Place the information repository in a location where the user can access it.
7. 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:

1. Locate the environment containing the relevant document that will answer their question.
2. Search the topics for the answer.
3. View the various topics that might contain the answer.
4. 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.

Read More

Pizza conflicts

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.

Read More

Dude, where's my document?

Try this experiment:

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

Done yet?

Now try this:

1. Using your Google or Gmail account, create a Google document.
2. Enter some text into it.
3. Open another copy of your web browser, or open a different browser.
4. Copy and paste the URL from one browser into the other. The document will now be displayed in both browsers.
5. Resize the windows of both browsers so that they are displayed adjacently to each other.
6. 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.

Read More

The New Medium is the Message

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.

Read More

Renaissance Man

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.

Read More

The Seven Lively Sins

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.

Read More

An OS is not O/S

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.

Read More