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.


A few good elements

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

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

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

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

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

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

Air. Fire. Earth. Water.

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

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

Topical Docs

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

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

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

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

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

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

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

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

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

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

Summing up, we have two very similar hierarchies:

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

The base component is the particle and topic. Merging the names particle and topic, we get topical, some that all our documentation should be.

A primer on primers

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

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

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

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

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

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

* * *

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

Within traditional documentation, primers include:

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

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

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

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

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

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

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

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

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

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

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

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

My Quantum-Mechanical Resume

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

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

Examples of hypo-professionals include:

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

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

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

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

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

“What is HTML?….And how do you spell HTML?”

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

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

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

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

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

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

Makes sense, right?

Well, not necessarily.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

To win the war in Afghanistan

  1. Find the enemy.
  2. Kill ‘em alot.

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

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

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

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

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

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

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

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

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

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

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

And view my resume here; it links to my bigger profile here.

The Mother of all Engineering Feats

Related imageBritish scientists were able to create human embryos with genetic material from one man and two women. The goal is to produce genetically altered “designer” babies and thereby eliminate hereditary diseases by combining the best bits of each person. It’s a controversial idea, but if saves lives and improves health, I’m all for it. Plus, you’d get to tell all your friends you have three parents – how cool is that?

Just as people have genetic strengths and weaknesses, so do technical communicators have strengths and weaknesses in their profession. Strengths in technical communicators include:

  • being friendly and outgoing
  • able to work quietly in solitude
  • able to work with a wide variety of people
  • able to work with like-minded people
  • a solid language background
  • a solid technical background
  • excellent written communication skills
  • excellent oral communication skills
  • able to see “the big picture”
  • an eye for detail
  • able to work in chaos
  • are comfortable with routine
  • able to follow existing standards
  • able to create new standards
  • able to view information textually
  • able to view information graphically
  • valuing simplicity over complexity
  • valuing completeness over simplicity
  • enjoy starting new projects
  • enjoy updating existing projects
  • able to work well with WYISWYG tools
  • able to work well with non-WYISWYG tools

As should be obvious, no single technical writer could possibly have all these strengths, because many of them contradict each other. The best documentation teams, therefore, have a good mix of writers from a variety of backgrounds.

I was once asked in a job interview this intriguing question:
Who would make the better technical writer?
a) Someone who studied language and writing, and then later learned technical skills
b) Someone who studied technical information, and then later learned language and writing?

The short answer is – we can’t know. The longer answer is: it depends what you mean by “better technical writer”. Either person may match the requirements of a particular job, and it is impossible to know from these brief descriptions who is the more apt candidate.

For example, I remember looking through medical textbooks a few years ago. They contain detailed pictures of human anatomy. Only two types of technical communicators could have created these images:

a) a graphic artist who learned anatomy
b) a medical person who learned art

There is no way to tell by looking at the illustrations which of these two communicators were responsible.

You can never be all things to all companies. You cannot be “the perfect writer”, however, you can be perfect for a particular job. You have a complex set of skills and traits – you “tech comm DNA”. Know your DNA, and you will know where you should be and what should be doing.

The Big Bang of Information

Related imageScientists are edging ever closer to discovering the deepest mysteries of the universe. The world’s largest particle accelerator, a monster of a machine with a circumference of 27 km, is now online. Named the Large Hadron Collider, this machine is so big it occupies two countries: Switzerland and France.

This accelerator smashes sub-atomic particles into each another at speeds approaching that of light, creating collisions of almost 14 trillion electron volts. (Almost enough to power Windows 7.) In doing so, scientists hope to recreate the conditions that existed immediately after the Big Bang, when the universe exploded into existence.

One popular misconception about the Big Bang is that it was an explosion of matter into space. In fact, it was an explosion of space itself. That is, space itself expanded, and continues to expand, into nothing. Now, it’s very hard to define nothing; one can only say it is the opposite of something.

There was some concern that the accelerator might actually create a black hole, and swallow up our galaxy. If that happens, I may have to suspend this blog for a while. Black holes notwithstanding, the Large Hadron Collider could prove the existence of the Higgs boson, also know as the “God particle.” If this particle can be recreated, it would have enormous cosmological implications, because it would prove the Standard Model theory of the universe, a theory that explains how all matter and energy are connected.

So, we have never been as close to the Big Bang as we are now. However, space is not the only thing that’s been exploding: so has information. There’s probably more information produced today in one second than was produced in a hundred years just a few centuries ago. Think of all the places information exists:

  • the Internet
  • computers
  • bookstores
  • signs
  • stickers
  • personal letters and documents
  • companies
  • governments
  • that big mess in the back of your closet

Billions and billions of pages, and it keeps growing like a monster. Soon even the universe won’t be big enough to hold it all.

Information has exploded as rapidly as the universe. But if the universe began as tiny particle, did all the world’s information begin as one? And, if so, how could we represent that?

We could start with the word itself: information. But this word can be further compressed and expressed simply as the letter i, the international symbol for information. [i] signs are visible at airports and other public places. People intuitively know that [i] = information.

In addition, i has two parts: a short upward line with a small dot on top of it. The line is an arrow, directing you to a dot. The dot is the point, literally. If your document does not make the necessary points, it has no point, and it is not useful information, but dark matter.

All information, therefore, began from the lowly i.

The i tells all.

The i is infinite.

The i is the i-ching of our profession.

No sex please, I’m neutral

In an extreme version of single-sourcing, Australian officials issued an immigration certificate with the Gender field listed as not specified.

The document was issued to immigrant Norrie May-Welby, who was born a man but later had a sex change operation. The procedure included taking female hormones, but after several years, this person stopped taking the medicine and decided to become a “gender-neutral”. “The concepts of man or woman don’t fit me,” he said.

Oops – I mean she said… I mean s/he said. (Damn these restrictive pronouns!)

A few points on this rather delicate topic.

1. Do the sex and gender fields of all government forms need to be revised to include “none of the above”?

2. If this answer to the above is “no”, how does one handle rare documentation cases such as these?

Technical communication ideally is as digital as the computer file itself. That is, every topic, concept, state and procedure is clearly defined with no ambiguities. True or false. 1 or 0. Binary or death.

Now, the best way to avoid confusion is to explicitly define your terms. All objects, actions and items must be clearly described using non-technical words which themselves need no further definition or explanation. Otherwise you end up with sentences like this:

To folicate the nefigog, you need to parrelify the actrawan.

Unfortunately, uncertainties and confusion sometimes occur. Or to put it more succinctly – sh-t happens. What then?

It all depends on the dreaded probability factor, which is:

A. the number of users who may encounter this situation
B. the number of times they might experience it

If this factor is high, then it indicates a flaw in the design of the product itself. If the usability and repair budgets are exhausted, and there will be no fix forthcoming, it falls upon the shoulders of the lowly technical communicator to openly document this heinous behaviour, probably in a number of places, for example: the ReadMe, the User Guide, the Install Guide, and so on.

If this factor is low, the exception can still be documented, but less frequently. For example, in the aforementioned “gender neutral” problem, given the few times this will occur, I would add a brief note to the field description, something like:

Select a Gender: M for Male, F for Female, O for Other.

Note: If you select Other, you can enter more detailed description, because we’re really curious to know just what the hell you are.

The Sixth Sense

Related imageWe all know (and love) our five senses: sight, hearing, taste, smell, and touch. Apparently, these senses are not enough. Science, psychology, and the arts have been on the hunt for a sixth sense since the time people knew they had senses.

Candidates for a sixth sense include:

  • intuition
  • emotion
  • intelligence
  • extra-sensory perception (ESP)
  • equilibrioception – the ability to balance

As a technical person, one of the candidates that I find particularly interesting is a device called, (what else?), the SixthSense.

The SixthSense is prototype information device you can wear. It consists of a computer, a pocket projector, a mirror, and a camera. The projector projects visual information onto any surface. The user wears colored markers on their fingertips. The camera recognizes and tracks the user’s hand gestures, kind of like in the film Minority Report.

There are many cool things that you can do with this device just by using your hands to virtually “draw” various shapes:

  • “draw” a magnifying glass to launch a map application
  • “draw” virtual shapes onto any surface
  • “draw” a frame to launch the camera
  • “draw” the ‘@’ symbol to check your email
  • “draw” a circle on your wrist to project a watch onto it
  • use hand gestures to flick through photos you’ve taken

Most importantly, SixthSense can detect different types of physical objects and then project additional, meaningful information onto them.

Examples include projecting:

  • live video news or dynamic news updates onto a newspaper
  • current airline departure information onto an airline ticket.
  • nutritional information and recipes onto food packages you are looking at the supermarket
  • book reviews onto a book
  • a person’s favourite websites onto the person’s shirt (yes, it really can do that!)

This device is a glimpse of a future world awash in meta-information. It is currently a prototype, and not freely available. However, the documentation we create is. For this, there are valuable lessons.

First – all technical communicators do have a sixth sense – the sense of information. And not just any information, but clear and meaningful information. We know, or can find out, what the user needs to know. We know how to give that information to the user. The only thing we don’t know is what what we don’t know. But we know that we don’t know what we don’t know, you know?

To find out what we don’t know, we speak with the people who do know. These are the other people involved with the product you are documenting. Particularly important are the people who are working with the users who actually use the product. These are the salesmen, product analysts, business analysts and others who have direct contact with the end users.

Second – our documentation should be as helpful as a SixthSense device. It should:

  • “know” the user
  • know what the user needs to know
  • give them the information they need to know
  • tell them how to get more or different information
  • withhold information they do not need to know

Do you agree? If not, I’m not worried.

You’ll come to your senses…

We’re here, we’re synesthesic, get used to it

Image result for synesthesiaSynesthesia is the ultimate mashup. It’s a neurological condition in which a person experiences the data of one sense with another – a sort of warped virtual reality.

Examples of synesthesia are:

  • seeing numbers and letters as colours: for example, where most people see the following text as black: ABC 123, a synesthesic might see it as: ABC 123
  • perceiving numbers, letters, days of the week and months as emotions or personalities: for example: 1 as “strong”, H as “envious”, Tuesday as “sad” and July as “jealous”
  • seeing sounds: a loud noise such as dog barking or fireworks exploding might cause the person to see certain shapes or patterns
  • perceiving time periods as locations in space: for example: Monday appears “further away” than Wednesday
  • “tasting” certain words or letters: for example, most tastes like toast, and leg tastes like egg

Scientists aren’t fully sure what causes synthesia, but agree it’s probably some sort of neurological malfunction in which the sensory wires in the brain get crossed. It may affect as many as one in 23 people.

Blessing or Curse?

At first glance, synthesia might seem like a curse. After all, who would want the distraction of “hearing” colours or “seeing” sounds? In fact, it may be a blessing. Some synthesics are very creative and have produced unique drawings and other artwork that illustrate the remarkable way they experience the world.

Synthesia, Tech Comm Style

An effective technical communicator is partially synesthetic. We simply would not be able to do our jobs well if we perceived information the same way normal people do.

Specifically, technical communicators are hyper-sensitive to vague, missing, misspelled, confusing, incomplete and poorly organized information. We perceive it as jarring, illogical, uncomfortable and painful. We can call this condition technical communication synthesia, or TCS.

TCS Examples

The following examples help illustrate TCS. In each one, you’ll see three statements:

  • Actual text – the actual text that might appear in a document or software application
  • Normal perceptionhow a normal (non-TCS) person perceives the text
  • TCS perceptionhow a person with TCS perceives the text
  • Actual text The record is updated.
  • Normal perceptionGreat! The record is updated. My work is done!
  • TCS perception The record is updated?! Who or what updated the record? The user or the computer? The objective voice is evil.
  • Actual text Welcom too the Synex Usser Giude .
  • Normal perceptionHmm, something doesn’t quite smell right…
  • TCS perception The horror; the horror…
  • Actual text The Sort command sorts your data.
  • Normal perceptionGee, who would have thought it did that?
  • TCS perceptionCircular references are evil! Change this to: Use the Sort command to arrange your data alphabetically or numerically.
  • Actual textThe program will remember your settings.
  • Normal perceptionAwesome! I can just set it and forget it!
  • TCS perceptionRemember? How can program remember?! Anthromorphization is evil!
  • Actual textError 43 – Incompatible file format.
  • Normal perceptionDamn! Where’s the tech support number?!
  • TCS perceptionWhere is the problem? What is the solution? And who cares what the error number is?
  • Actual textAbort the process.
  • Normal perceptionYikes! I’d better stop the process.
  • TCS perceptionAbort is a word more loaded than an H-bomb. Change to: Stop the process.
  • Actual textIt’s important to back up your files.
  • Normal perception – That’s nice to know….uh, what’s a “back-up”?
  • TCS perception – What is a back up? Why is it important? How do you perform one? Which files do you back up? How often should you perform one?
  • Actual textDo you want to enter more records? [OK] [Cancel]
  • Normal perception – Yes, I do, so I’d better click OK .
  • TCS perception – Ouch! Why can’t developers label buttons properly?! Change the buttons to a simple [Yes] and [No].
  • Actual textTurn off your computer. Be sure you have saved your work first.
  • Normal perceptionOK, I’ve turned off my computer Now what? Make sure I’ve saved my work first?! Doh!
  • TCS perceptionMight as well say: Cut the red wire to detonate the bomb. Change to: Save your work, then turn off your computer.
  • Actual textTo print a document, make sure you have opened the document you want to print, the printer is on, there is paper in the paper tray, and that the printer has enough ink, then press Print and select the correct printer, paper size, orientation, the pages you want to print and the number of copies, then click OK.
  • Normal perceptionYou had me at “To print“. Then you lost me. I am sad.
  • TCS perceptionCould that sentence be any longer? Rewrite to:
To print a document:
  1. Ensure the printer is on.
  2. Check that there is paper in the paper tray.
  3. Check the ink level of the printer.
  4. Open the document you want to print.
  5. Click the Print button.
  6. Select the paper size and orientation.
  7. Select the pages you want to print and the number of copies.
  8. Click OK to print.

Note: TCS is incurable, thankfully.