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