Category Archives: science

My Quantum-Mechanical Resume

Posted on by

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.

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

Portability
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 andrew-brooke.ca.

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

The Mother of all Engineering Feats

Posted on by

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

Posted on by

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

Posted on by

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

Posted on by

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

Posted on by

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 perception – how a normal (non-TCS) person perceives the text
  • TCS perception – how a person with TCS perceives the text
  • Actual text – The record is updated.
  • Normal perception – Great! 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 perception – Hmm, something doesn’t quite smell right…
  • TCS perception – The horror; the horror…
  • Actual text – The Sort command sorts your data.
  • Normal perception – Gee, who would have thought it did that?
  • TCS perception – Circular references are evil! Change this to: Use the Sort command to arrange your data alphabetically or numerically.
  • Actual text– The program will remember your settings.
  • Normal perception – Awesome! I can just set it and forget it!
  • TCS perception – Remember? How can program remember?! Anthromorphization is evil!
  • Actual text – Error 43 – Incompatible file format.
  • Normal perception – Damn! Where’s the tech support number?!
  • TCS perception – Where is the problem? What is the solution? And who cares what the error number is?
  • Actual text – Abort the process.
  • Normal perception – Yikes! I’d better stop the process.
  • TCS perception – Abort is a word more loaded than an H-bomb. Change to: Stop the process.
  • Actual text – It’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 text – Do 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 text– Turn off your computer. Be sure you have saved your work first.
  • Normal perception – OK, I’ve turned off my computer Now what? Make sure I’ve saved my work first?! Doh!
  • TCS perception – Might as well say: Cut the red wire to detonate the bomb. Change to: Save your work, then turn off your computer.
  • Actual text– To 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 perception – You had me at “To print“. Then you lost me. I am sad.
  • TCS perception – Could 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.

How Long is a Piece of String Theory?

Posted on by
“If you need to get some string, get this string. It’s the greatest string in the world. It’s almost rope.”

You can’t get more deadpan than the brilliant observational comedian Steven Wright, who is imagining the ultimate ad to sell strings. Strings are as commonplace as cellphones these days. In addition to the plain old strings Wright describes, you can have:

  • stringed instruments
  • pearls on a string
  • a string of islands
  • drawstrings
  • a string of ideas
  • string beans

You can pull strings, be strung out, string a person along, be second string, string lights, and keep someone on a string. When it comes to describing this particular object, there’s simply no strings attached.

The Mother of All Stings

Leave it to theoretical physicists to make something as simple as a string the foundation of one of the most complex and fascinating scientific theories ever imagined: string theory.

String theory proposes that everything in the universe is made up of tiny, vibrating strings of energy. The way the strings vibrate determines the type of particle formed. In this theory, strings make up quarks, which in turn comprise electrons, protons and neutrons, which make up atoms and finally molecules.

If string theory could ever be proven, it would literally be the answer to the universe. That’s because string theory is a unified theory, a theory that unites the study of the very, very small (quantum mechanics) with the very, very large (general relativity). It would explain how all matter behaves, from the components of atoms, all the way up to planets and galaxies. That’s why a unified theory is also called a theory of everything.

My, What Small Strings You Have

The problem is that it may be impossible to prove string theory. The strings would have to be unimaginably small: a string would be to a hydrogen atom what a small tree is to the solar system. If strings exist, their tiny size would make them unable to be detected directly. Also, for the math in string theory to work, the strings have to exist in eleven dimensions. (I have enough trouble with multiple text conditions.)

What’s really fascinating, though, is the idea that by determining the basic building blocks of the universe, we can solve the mystery of the universe. Now, if we could identify the basic buildings blocks of technical communication, it could be a unified theory for our profession.

I Object

Initially, it would be tempting to identify the basic tech comm objects as the actual language or visual constructs used when communicating, for example:

  • letters, numbers and symbols or
  • words and pictures or
  • nouns, verbs and objects or
  • overviews and tasks

While it’s true these elements are all used to assemble documentation, realizing this doesn’t bring us any closer to exactly what technical communication is or does. In fact, taking things to their logical conclusion, all communication is made up of ink or pixels, but this doesn’t explain anything.

We need to ask: what is the true purpose of technical communication, and what does it actually mean to achieve this purpose?

Tech Writing On Purpose

The purpose of technical communication is to give users the information they need to understand concepts and complete tasks. That is, all technical communication is made up of two basic components:

  • conceptual explanations or overviews
  • procedural explanations or procedures

These are the two types of technical communication to be unified, just as string theory attempts to unify the small and large. We need to identify the common elements in each type, and then see if they can be synergized.

Let’s start with overviews. To have a user understand a concept, we need to explain that concept to them, and wherever possible, show a real-world example. (An example would be appropriate here.) For example, to explain what character formatting is, you could show examples of bold, italic and underlined text.

For procedures, we need to tell users what the procedure does, any prerequisites, why a user would (or would not) perform the task, and what the end result is.

Elementary, My Dear Reader

So what are the elements in a procedure? In a procedure, a user performs an action on an object, with some specific result. We could therefore list the elements as:

[user] [action] [object] [result]

So, for example, when a user updates a file:

  • the action is the process of updating the file
  • the object is the file
  • the result is an updated file

Let’s keep this mind for now and look at overviews. In a conceptual overview, a user reads an explanation of a concept and then, we hope, comes to understand that concept. We could therefore list the elements of a conceptual overview as:

[user] [concept] [understanding]

For example, a user reads an explanation of a database, and then comes to an understanding of what a database is and why they would use or create one.

All Together Now

Bring these two list of elements together, we get:

Procedures: [user] [action] [object] [result]
Overviews: [user] [concept] [understanding]

We can remove [user] from both lists. The user is the receiver of the document, but is not actually part of the document.

We now have:

Procedures: [action] [object] [result]
Concepts: [concept] [understanding]

[action] can be replaced with the more general . When you define an action or step, you are really creating an explanation for that step.

[understanding] can also be replaced with . The user understands, but the document explains.

We now have:

Procedures: [object] [result]
Concepts: [concept]

[result] could be more generically referred to as [state]. That is, in a procedure, an object moves from one state to another: a field is completed, a record is updated, a document is printed, and so on.

[concept] can also be generally referred to as an [object]. Although concepts can cover tangible items such as files, fields, and records, they can also apply to actions such as printing, saving, and copying. The action becomes of the object of the explanation. So whether you are describing a thing or non-thing, that item becomes the very object you are trying to explain.

We now have:

Procedures: [object] [state]
Concepts: [object]

At this point, it would be tempting just to simply remove [state], thereby making both lists of elements identical, and solve this puzzle. However, [state] is such an important aspect of documentation we cannot eliminate it. Instead, let’s see if there’s a way to add [state] to concepts.

State of Grace

What happens when a user understands a concept? The user moves from being in a state of ignorance to a state of awareness. However, we’ve already said that the user is not actually part of the documentation, only the object is. From the object’s point of view, it moves from being in an unknown state to a known state. That is what an effective conceptual overview must do.

We can therefore add [state] to concepts and derive the solution:

Procedures: [object] [state]
Concepts: [object] [state]

That is, all documentation consists of these three basic elements in various forms:
[explanations] [objects] [states]

Does this have any practical application? Well, it can serve as a high-level checklist of whether a topic has been effectively written.

Specifically, if a topic does not clearly:

  • identify and define an object
  • offer a clear explanation of the concept or task
  • indicate the change in state of the object (for a task) or actually change the state of the object from unknown to known (for an overview)

then the topic has failed.

So there you have it – a rudimentary theory of everything for documentation. And we only needed two dimensions to do it.

The Matter of Dark Text

Posted on by

Physicists have many odd ideas, but one of their oddest surely is dark matter. It is the dense, invisible stuff which fills the universe, but its existence can’t be proven directly, hence the term dark. It also has a sister: dark energy. Dark energy, like dark matter, is also invisible and cannot be directly proven to exist. However, dark energy appears to explain why the universe is not only expanding, but doing so at an accelerated rate.

Scientists are working hard to find out which of these two things is more abundant in the universe. If there is more dark matter than dark energy, then the gravity of the dark matter could eventually cause the universe to stop expanding and then start shrinking, collapsing into a single point, in a very noisy event called a “big crunch”. Alternatively, if there’s more dark energy than dark matter, it could mean that the universe will continue to expand but, like spots on an expanding balloon, everything will be pulled further and further away from each other, resulting in a very cold, lonely universe.

The good news is that either scenario won’t happen for billions of years. The bad news is that in either case, all living things will cease to exist. To paraphrase Einstein, “Bummer.”

Fortunately, the other two qualities of our universe, space and time, don’t have a corresponding “dark” component; that is, there’s no such thing as dark space or dark time, except perhaps on Star Trek. However, there is a corresponding component in our profession, and it is called dark text.

Dark Text Matters

Dark text refers to the many layers of hidden meaning in any text segment. It ranges from the implied meaning that the author intended, or that the reader infers, to much deeper, more hidden meanings.

Here’s a simple example:

To print a document, click Print.

The dark text of this step is:

  • a document is a piece of paper
  • you’ll need a printer to print something
  • “clicking” involves position the cursor on a monitor over a certain graphical element
  • the printer must be connected to a computer and must be configured correctly

Darker text could include:

  • you should be careful before you print something: once it’s printed, you can’t “undo” it
  • the printer must have toner and paper; electricity would also be helpful
  • if you can’t figure this out, call your 11-year old relative who knows more than you do about computers

There’s Nothing Funny About Funny Money

Here is a more interesting example. In stores, you often see this sign:

We do not accept $50 or $100 bills.

The first level of dark text is derived from the fact that this statement does not explicitly tell the reader what to do or not do. So the “obvious” (or lighter) dark text is:

Don’t even try to give us $50 or $100 bills.
The next level of dark text is:

We don’t want counterfeit money, which typically is $50 or $100 bills.

However, there is a third level of dark text, which is darker (and more sinister) than these two other levels.

Because we don’t accept $50 or $100 bills, we will accept $5, $10 and $20 bills, even if they are counterfeit.

This, in fact, is exactly what has been reported by the authorities. Counterfeiters know that unless stores are checking every bill they get, they will simply assume the lower denomination bills are legitimate. These stores have inadvertently given a sign to these criminals that they will take their fake money.

What, then, should the sign say, to scare away any potential counterfeiters? Perhaps something like this:

WARNING! We check all paper currency to make sure it is not counterfeit. If you try to use counterfeit money here, you will be caught and prosecuted to the fullest extent of the law. Punishment can include a major fine and imprisonment for up to 14 years.

Note that most of the dark text has been removed. This is what is known as “writing from the user’s perspective”.

* * *

As technical writers, we must be aware of dark text, and where possible, try to minimize it. It’s true that we cannot possibly document all of the hidden meaning in text, nor should we. Still, much information may be hidden or very subtle and must be exposed or more clearly stated. To decide when to expose dark text, you need to ask yourself:

Would a typical user need to know this fact in order to more effectively use the thing I am documenting?

The goal is to give users all the information they need to do their jobs, and no more than that. This is an axiom of technical communication, and will be so until the end of the universe.

Virus’d!

Posted on by

Related imageNo, this article is not about how my computer has been infected. Many younger people today may find this hard to believe, but before there were computer viruses, there were biological ones.

A virus is a machine more perfect and efficient than anything mankind could manufacture. It is a difficult beast to describe; scientists aren’t even sure whether it is “alive” in any sense of the word. That’s because viruses contain genes but no cell structure or metabolism, considered critical to life.

Whatever viruses are, they have a somewhat poor reputation, because they have probably killed more people than all wars and murders combined; not millions, or even tens of millions, but hundreds of millions have been slain by something the poor victims couldn’t even see.

Viruses come in essentially three different flavours: the good, the bad and the ugly, and the ugliest one of all is Ebola. This monster can kill within several days, and it does it in a most horrific way: it essentially liquefies your organs from the inside. Victims bleed to death from the inside out.

What’s interesting is that Ebola, like all deadly viruses, does not actually intend to kill its host. It’s simply making copies of itself, because that’s what it is programmed to do. Essentially, it is trying to turn its host (a person) into a giant copy of itself. In the process, it destroys the host. Hence, their nasty reputation.

But what if you could make a good virus? In fact, such viruses have been developed. Years ago it was discovered that milkmaids who had been infected with the relatively mild cowpox virus were immune to the much deadlier smallpox virus. This led to smallpox vaccination. In fact, most vaccines today contain weakened versions of viruses that protect you against the nastier ones. In genetic medicine experiments, harmless viruses carry useful genes into cells. For example, scientists have tried treating a genetic disease by letting a virus insert a crucial gene into liver cells that protects against harmful cholesterol.

Therefore, we should not always fear the virus. In fact, we can learn much from it. Earlier I said how viruses are simply trying to make their hosts into copies of themselves. That is precisely what an information developer is trying to do to the reader. A successful information developer infects the host agent (the reader) with the knowledge already contained in the information developer’s mind. In doing so, the developer is creating copying the information into the reader’s brain. The more efficiently and accurately the information developer can do this, the better the infection.

And the best part is, that, unlike the Ebola virus, the reader’s brain won’t be liquefied in the process. Unless you are a really, really poor writer. Unfortunately, there’s no vaccine for that.

Facing Off New Technology

Posted on by

Image result for face off movieA remarkable event occurred in Cleveland a few weeks ago. In a marathon surgical procedure, a team of eight doctors worked 22 hours to transplant a woman’s face, moving bone, teeth, muscle and nerves. It was the first facial transplant in the United States, and only the fourth in history.

One of the doctors vividly described the procedure: “We transferred the skin, all the facial muscles in the upper face and mid-face, the upper lip, all of the nose, most of the sinuses around the nose, the upper jaw including the teeth, the facial nerve.” These incredible technical craftsmen have truly “saved face”.

I remember the 1997 action science-fiction film Face/Off. In it, a policeman and a criminal mastermind switch identities through a facial transplant, with rather unexpected results. Science fiction has become science fact.

Now, if these doctors can transform a person’s face, it obliterates all excuses for not transforming the way we create documentation. Converting thousands of pages of legacy documentation to a structured format is very difficult. But impossible? Impossible occurs when you lack either the will or the means to accomplish something. Let this event in Cleveland inspire us all.