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.


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…


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

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

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

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

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

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

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

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

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

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

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

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

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

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

A Lasting Theorem

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

For the equation: an + bn = cn, 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:
32 + 42 = 52 and 52 + 122 = 132. 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 backwards 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 proof that verifies that the number of end users in the world is identical to the number of technical communicators.

Unfortunately, this blog is too small too contain it.

Pizza conflicts

Image result for pizzaMy pizza user guides are hurting my head.

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

What’s a hungry tech writer to do?

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

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

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

Dude, where’s my document?

See the source imageTry 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.

The New Medium is the Message

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

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

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

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

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

Documentation Formats
The type of documentation delivered.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The medium and the message have become one.

Renaissance Man

Image result for Leonardo da VinciWho among us would not strive to be that most self-actualized of persons, master of many fields, an intellectual powerhouse, knowledge warrior and universal genius known as a Renaissance Man.

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

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

Renaissance Communicators are:

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

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

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

It’s a Renaissance, man.

The Seven Lively Sins

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…

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.

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.

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.

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

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

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

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

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

Let us be…wrath.

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

An OS is not O/S

See the source imageBeing 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.