The Doc Particle

Never has something so small attracted so much attention. In July of this year, scientists at the Large Hadron Collider, the world’s largest particle accelerator, claimed to have discovered the oddly named Higgs-boson particle. (And it only cost them $10 billion to find it.)
This tiny particle is also known as the God Particle because it could explain why things exist.  Discovery of the Higgs-boson particle helps prove the existence of something even more bizarre: the Higgs field. This is an invisible force field which covers the entire universe, allowing subatomic particles to have mass. Without mass, electrons, protons and neutrons wouldn’t be able to form atoms, and therefore nothing would exist.
This discovery could lead to some amazing things. If scientists could actually control the Higgs-boson particle, we could travel at the speed of light and change matter. Science fiction would become science fact.
The idea that there’s a force holding everything together is fascinating. We think that things just are – that they exist in a simple, natural state. The fact that things may not be so simple, that it actually requires a force to hold everything together and give a structure to all matter, is mind-blowing.
But the question for technical communicators is this: what is the force that holds all content together? By content, I mean any organized collection of information that forms a document, help system, website,  or any other form of visual communication.
Whatever this force is, it must be as powerful as the Higgs field, for without this force, content would descend into a universe of chaos, with thousands, if not millions, of elemental pieces of information flying off in every direction.
  • Topics would have no context or structure.
  • Concepts would have no meaning.
  • Indices would include non-existent entries.
  • Tables of content would cease to exist.
  • Tasks, the backbone of many user guides, would describe inaccurate or irrelevant steps, and would omit key steps.
One shudders to think how it would all look, but having an engineer write a user guide gives a fair approximation.
So just what is the force that holds all this content altogether? The answer is so obvious that you would not even suspect it – it is technical communicators. We are the force that holds content together. We create it, shape it, fine-tune it, and then re-shape it again until it forms a living system of information that is practical and meaningful to the end user.
We have seen the God Particle of content, and it is us.

A Transcendent Man

Related imageIf 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…

A Relatively Unique Document

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

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.

1There are two absolute “speed limits” in information development:

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

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

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

Read part two.

Another Relatively Unique Document

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=mc2, Einstein’s famous equation uniting mass and energy. This formula indicates that a small amount of mass contains a tremendous amount of energy.

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

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


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.