An Echo from History

One of Sting's finest songs is Children's Crusade - his haunting lament on the follies of war, specifically, the First World War.

Here are the relevant lyrics:

Young men, and soldiers, Nineteen Fourteen
Marching through countries they'd never seen
Virgins with rifles, a game of charades
All for a Children's Crusade

Pawns in the game are not victims of chance
Strewn on the fields of Belgium and France
Poppies for young men, death's bitter trade
All of those young lives betrayed

The children of England would never be slaves
They're trapped on the wire and dying in waves
The flower of England face down in the mud
And stained in the blood of a whole generation

Corpulent generals safe behind lines
History's lessons drowned in red wine
Poppies for young men, death's bitter trade
All of those young lives betrayed
All for a Children's Crusade

This wonderful and majestic piece sounds as fresh today as it did when it was released 25 years ago in 1985. (Wow, has it been that long?)

Although more people died in the Second World War than the first, in many ways, the First World War was more horrible because of the sheer senselessness in the way it was fought. Hundreds (and sometimes thousands) of men would be killed just to gain a few feet of ground, which would often be lost the next day. There was no concept of modern warfare - it was often just organized chaos.

One of the Canadian soldiers who fought in the First World War was Fred Albright, a prominent young lawyer from Calgary, Alberta. He met a woman named Evelyn and they began writing each other quite frequently. They married in 1914; three years later Fred was killed at the battle of Passchendaele.

Their correspondence both before and during their marriage represents an enormous volume of personal documentation. Together, they wrote over 550 letters covering a wide range of topics. Even after Fred died, Evelyn continued to write him in a effort to deal with her grief.

This incredible glimpse into history would have been lost forever but for the efforts of a library assistant who discovered the letters while working at the Archives and Research Collections Centre in the D.B. Weldon Library at the University of Western Ontario. Fascinated by the letters, she painstakingly transcribed and edited their contents so that they could be posted to a website entitled: An Echo in My Heart.

By the way, the assistant is my mother.

You may go back in time here....

Read More

Resolve this

My new year's resolutions all involve documentation, of course.

The Paper Chase

My first resolution is to organize all the various printed guides, warranties, and other paper documents that have accumulated over the years and randomly spread themselves into various piles throughout my home.

I will review each and every paper item and discard what I don't need. (I hate paper and wish we lived in a paper-free Star Trek world.) The relevant leftovers will be grouped and placed into large envelopes and stored alphabetically in a box.

My extensive printed documentation collection includes the following:

• big electronics - TVs, Blu-Ray and DVD disc players, CD player, home theatre and satellite receiver, gaming unit
• little electronics - MP3 players, cameras, phones, remotes, clocks, shavers, hardware tools, watches, electric toothbrush, organic mind reader
• main computer items - user guides, and guides for the motherboard, DVD burner, RAM
• peripheral computer items - mouse, monitor, keyboard, speakers, scanner, Webcam, backup drive, software documentation, USB powered teleporter
• kitchen appliances - fridge, stove, microwave, dishwasher, blender, toaster oven, indoor spit
• garage items - snowblower, lawnmower, trimmer, BBQ, Ferrari guide
• miscellaneous items - washer and dryer, vacuum cleaners, non-electric items such as board games, hot water heater, humidifier, kitchen faucet, Sherman tank

(God, I have a lot of crap.)

Soft Sell

My second resolution is to conduct a complete audit of all the soft documents on my computer and again, get rid of what I don't need and keep the good stuff. There's many documents that are several years old that I never read and know I'll never need. Other documents need to be rewritten, merged or reclassified.

Onward and Online

My final resolution, a continuation of the second, is to move as many of my files online as possible. As long as the document does not contain sensitive or critical financial information (like my Swiss bank account number and Tiger Woods' cell phone number), I will move it to Google docs.

In addition to textual documents, my most precious files are my photographs. Before the era of digital photography, people took pictures with something called a film camera, which produced something called prints. I have hundreds of these prints in special books called photo albums. They are single copies only - there is no backup. My long term goal, therefore, is to scan every one of these photographs and upload them to private albums on Flickr.

Managing Catastrophe

I have heard of too many cases where hard drives have failed and people have lost all their files. Backups help with this problem, but if your house burns down or is burglarized, they have no value. The ideal state to be in if you lost your hard drive for any reason would be that you simply buy another computer, connect to the Internet, and access all your files.

Confidential files should be whittled down to a size that can fit on a USB key. That key should then be kept at a location away from your computer. Alternatively, you can use an online backup site. ADrive, for example, gives you 50 GB of free online storage.

Is this ringing any (alarm) bells?

If any of these documentation issues sound familiar (a plethora of printed docs, unorganized soft docs, and lack of an off-site backup for your documents and photos), welcome to the club. Most people simply don't make the effort to deal with these ongoing doc issues.

However, we technical communicators are not most people - we are the Communicati - the enlightened communication and documentation high priests. If we fail to maintain our own documentation, what chance do normal folk have?

Read More

The draft from Copenhagen

Let me see if got this straight: hundreds of leaders, civil servants, and NGOs gathered from all over the world in Copenhagen to address the problem of global warming.

They flew in using private jets, were driven around in gasoline-guzzling limousines, and ate gourmet food flown in from hundreds of kilometers away in order to create an accord that would deal with the excessive use of our limited resources.

Millions of dollars were spent hosting the summit. Enormous effort was expended in the countless meetings and negotiations.

The final result?

A three-page, non-legally binding document that has no long-term targets for cutting greenhouse gas emissions.

Even if this document were binding and had targets, given the political and economic realities of the time (i.e., governments don't want their citizens rioting due to lack of work), it is extremely doubtful this accord would actually have been implemented. (Do any countries actually follow the Kyoto accord?)

Never before has so much money, time, and effort been spent to produce such a thin document of so little value.

Actually, it's a wonder that even this document was produced. Given how difficult it is to get consensus on a simple user guide, giving two weeks for 120 of the world's leaders to agree on a document that could change the world is an impossible task.

It's like trying to write every software guide that has ever been written from scratch...

...in a one-week period...

...using only two tech writers.

Read More

Just watch me

I bought a new watch recently - digital, of course; I don't do analogue.

It's a watch only a tech writer could love: the day, date and time are clearly visible with massive fonts on a over-sized display.

Imagine my disappointment when after taking it home, I discovered the wrong user guide had been included. I tried to find the guide online, but, incredibly, it was not available on the manufacturer's website. (Fortunately, I was able to figure out how to set the time.)

So many user guides; so few tech writers to get them online.

Read More

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

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

Read More

The $53 million document

The final report from the five-year long public inquiry into child abuse allegations in Cornwall, Ontario has finally been released.

The price tag for this document? A staggering $53 million.

The report itself is 2,400 pages. That's just over $22,000 per page.

Assuming 500 words per page, the cost is about $44 per word.

We need to have a public inquiry into the cost of all these public inquiries. I offer my services in developing the final report.

And I'll only charge $43 per word.

What a bargain....

Read More

The World, On Demand

Just as a shoemaker's kids go barefoot and doctors makes the worst patients, us techy types are often the last ones to use newer technologies. How else to justify my delayed entrance into the wonderful world of podcasting and BitTorrents? My lame rationalization is that I wanted to be sure they got all the bugs out first; it's not like you can call 1-800-BIT-TORRENT for help.

Both these technologies are simply different flavours of the same thing: getting the file you want and experiencing it when you want. Podcasting is mostly for audio files (although video podcasts are available) and BitTorrent is for video files such as films and TV shows. Podcasting is fairly easy, hence its popularity. You simply download the MP3 file you want to your portable player, and listen to it.

Using BitTorrent is a bit trickier, because it involves changing hardware settings and using several different types of software. Most people do not have the technical expertise to do this, thank God, because if they did, the Internet would slow to a crawl. But as the difficulty decreases and bandwidth increases, expect to see more people using this technology. In fact, software such as Vuze, an "all-in-one" BitTorrent searcher, downloader, decompresser, and viewer makes finding and viewing torrents easier than ever.

In essence, we're seeing video availability catching up to information availability. Currently, you can locate information (text and graphics) on pretty much any subject. It is the golden age of information accessibility and variety.

Once it becomes as easy to find and view a desired program as it is to find desired information, the old broadcast model in which you have to wait for a program and watch it on the network's schedule will disappear.

Now, personal and DVD recorders have helped, but they still can't deliver shows that you forgot to record in the first place, or were not even aware of but might be interested in. YouTube and other websites offer streaming video on demand, but the picture quality is poor - for now, that is. Funny thing about the future - it's hard to predict, and it never ceases to arrive and amaze.

Read More

Nutritional Information Development

For a marvellous analysis of what's wrong with Canada's nutritional information labels, view this PDF developed by the Nutrition Action Newsletter.

Pay special attention to page two of this PDF, which details how the label should look. The design of this page, the suggested improvements to the label, and the way these improvements are documented should be required reading for all information developers.

Read More

Complication Nation

I'm getting emotional over motion. "Motionflow" TV must be one of the dumbest inventions ever. Oh, it sounds great in theory: a video display technology which reduces the blurring of rapid motion, making it flow more smoothly. The problem is it works too well. Watching a movie on a MotionFlow TV makes the film look like a cheap video. I mentioned this to a hapless TV salesperson - his feeble response was that you could turn off this so-called "feature". (To be fair, MotionFlow is probably best for sports and live TV, but I'm a movie guy myself.)

MotionFlow is a symptom of a bigger problem: companies designing products crammed with features that people either don't need, don't want or can't use. Ever tried to buy a cellphone that only makes phone calls, or a printer that only prints? You'd have better luck getting through to a live tech support person in less than two minutes.

The "overcomplication" problem hits our profession in two ways. First, in the tools we use. Yes, there are many good authoring tools out there. But many of them have far more features than you would ever need. For example, I have yet to find a simple, off-the-shelf, easy to use XML publishing system, one that would let you quickly create documents, TOCs, and indices, and publish them to a content management system. (If you know of one, let me know.)

More importantly, "overcomplication" is a problem in documentation. I've seen many documents that have far too much information in over-sized topics that are difficult to read. That's why I admire quick start guides. They give users the essential information they need to set up and use a product. The other content can be moved to a regular user guide or reference guide.

So the next time you're thinking about getting the latest version of Super-Duper Authoring Tool Version 127.3, or releasing a fun-to-read 800 page user guide, don't go with the flow; instead, de-complicate.

Read More

Deception: The User Guide

Imagine being asked to develop a user guide for spies instructing them on how to deceive others using techniques based on magic tricks. Sounds crazy, right? Yet that is exactly what U.S. magician John Mulholland was asked to do by the CIA in 1953. His guide was recently discovered.

The guide, titled The Official CIA Manual of Trickery and Deception, describes itself as follows:

The purpose of this paper is to instruct the reader so he may learn to perform a variety of acts secretly and undetectably. In short, here are instructions in deception.

The guide includes such chapters as Surreptitious Removal of Objects, Working as a Team, and my personal favourite: Special Aspects of Deception for Women.

Some of the procedures include:

• tying your shoelace to give out important information
• secretly poisoning someone's drink
• looking dumb
• stealing a document
• hiding powder in a hollowed-out pencil
• working with a clandestine partner

Oh, to be a tech writer for the CIA....

Read More

The Doc Surge

Let's talk effective project management. Imagine a particularly large and complex project. The top manager has laid out the terms. More resources are being committed. The project's objective has been stated, and, most importantly, an end date given.

The leader is the U.S. President. The project is the war in Afghanistan. The resources are an additional 30,000 troops, at a cost of $30 billion, or a cool $1 million per soldier. The objective is to win the war. The end date is July 2011, depending upon how the security situation improves; this is what's known as "conditional text".

Let's hope the final result is better than what I've seen on other projects, namely software and documentation development ones. Many companies don't invest enough in their information development and management departments.

The troop surge represents a 43% increase in the number of soldiers. Can you imagine the effect if a company increased the number of its tech writers the same amount? It would annihilate much of the company's misinformation and missing information, a true victory in the war on error.

Read More

Un-super Size Me

It's astounding that the very people whose job it is to be concise fail to be concise on their most important document: their resume. I plead guilty to this word-crime.

After consulting with an expert, I reduced my resume from 650 words to 300. How? By hacking off the crap that had accumulated over the years, and then simplifying the leftovers.

My resume is now a page and a half and can be read in 20 seconds. Considering the mountains of lengthy resumes employers must sift through, a short and concise one is a breath of fresh air.

Isn't this extreme editing? Yes, it is. Try it; you can always back up your super-sized resume.

Read More

Introducing the New & Improved Citizens Guide!

The Canadian government recently updated their guide for new Canadian citizens: Discover Canada: The Rights and Responsibilities of Citizenship. Apparently, the last release had a few omissions. In the current version, there's more information on Canada's history, and a greater discussion on our nebulous "Canadian values".

As an former immigrant myself (my family came over from England in the 1970s), I appreciate the handy new information in this guide. Apparently, it's important to have a job, and the guide even makes a suggestion for this. It says joining the army is: "a noble way to contribute to Canada and an excellent career choice." I guess I should quit my career as a tech writer and sign up. Or perhaps I could be a covert Military Tech Writer. I can picture me stationed in Baghdad, with the sergeant barking out the order: "Dammit, Brooke. I need that quick start guide and I need it now!"

The guide also lets new citizens know that "barbaric cultural practices that tolerate spousal abuse, honour killings, female genital mutilation or other gender-based violence" are forbidden. I'm sure that information will come in handy. Picture this discussion:

Crazy father: I'm sorry, daughter. I saw you with that boy whom I'm forbid you to be with. I'm afraid you must be sacrificed for the family honour.

Innocent Daughter: Sorry - you can't. It's specifically forbidden on page 32 of The Guide.

Crazy father: Oops! You're right. I must have missed that section. Was it in the TOC?

Let's analyze the potential users of this guide. The vast majority of immigrants who come here do so precisely because they want to escape the horrors of their former countries and live in a peaceful, secular, democratic state. They know these types of acts are illegal here. The tiny minority that think they can commit these crimes are not going to be swayed by a manual.

It takes much more than a guide to make someone a successful citizen. As with all documentation, guides may help, but, in the end, the user must choose to learn.

Read More

Remembering The Wall

Twenty years ago, the wall came a-tumblin' down in Berlin. Bewildered East Berliners flowed into the west, marvelled at the material delights, then returned to their drab homes. About a year later, in the greatest act of single-sourcing in history, East and West Germany were merged into a single entity.

I was lucky enough to have seen the wall only three years earlier, in 1986. Berlin was one of the many stops of my grand tour of Europe: 22 countries in 60 days. I remember scrambling to the top of an observational platform near the wall. I, along with about 20 other insane college students, crammed together at the top, where we could easily see over to the other side. We saw the wall on our side, a "no-man's land" strip about 300 feet wide, and finally the wall on the East German side, where East German soldiers laughed at our packed-together motley crew.

If you had told me that three years later these walls would be gone, I would have said: "Yeah, right. And someday all the world's computers will be magically connected, everyone will have their own portable phone, and you'll be able to buy TVs 3" thick and 52" in diameter. Like that's ever gonna happen..."

Many people don't realize the two walls ran not only through a city but through the entire country. I wonder what happened to all the concrete? It would have been tough to recycle it.

Off the Wall

We must be thankful to live a country that has no walls to imprison its people. (Except for the ones in jail, of course.) However, there all walls of other sorts. The walls that wreak havoc in our profession are the ones blocking the free flow of information. Companies build virtual walls (or silos) around their various departments, resulting in misinformation, disinformation, inconsistent information, little information or no information being circulated amongst the employees.

In software companies, a business unit for a specific product can be comprised of developers, QA testers, marketers, salespeople, trainers, technical writers and product managers. How often do these people communicate with each other and share information? If they're not communicating, they are building - building the wall.

So I say to these workers, and to the company presidents, vice-presidents, CEOs, and managers at all levels:

Tear down these walls!

Read More

How Long is a Piece of String Theory?

"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 [explanation]. When you define an action or step, you are really creating an explanation for that step.

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

We now have:

Procedures: [explanation] [object] [result]
Concepts: [explanation] [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: [explanation] [object] [state]
Concepts: [explanation] [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: [explanation] [object] [state]
Concepts: [explanation] [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.

Read More

H1N1 A1 Confusion

The media's endless drive for ratings has us all convinced we're about two minutes away from certain death. To be sure, the H1N1 virus (the artist-virus formerly known as "Swine Flu") can be lethal. But let's have some perspective: more people will die from the regular flu than this nasty variant. More will also die from car accidents, obesity, alcohol, smoking and many other plagues, but why let relevant comparisons get in the way of a juicy news story?

To Save Your Life, Please Take a Number

The latest news concerns the vaccine production problems. Contrary to earlier reports where the various levels of bureaucrats assured us there would be plenty of vaccines for all, there's actually a severe shortage. Persons not in one of the "priority groups" need not apply for the antidote. Pregnant women, children and health care workers on the lifeboats first, please. As for the rest of us - not to worry - we'll have that iceberg removed in no time.

Great Expectations Not So Great

Now, imagine if the government had stated at the beginning only a limited quantity of the vaccine would be available. They would still have been criticized, but not to the same degree. The problem was a high expectation was set, and very badly went unmet. The end users (the public) don't care whose fault it was. All they know is they and their family are not getting their shot.

We can learn from this in the business world. Never set expectations too high, for if you miss them, you'll be a failure no matter how great a document you deliver. Always under-promise and thereby over-deliver. If you think it'll take N number of weeks to produce the guide, substitute 2N for N. That is, double the time you think it will take. The worst that can happen is you'll get it in "early".

To Vaccinate or Not to Vaccinate? That is the Query

The second major H1N1 controversy is whether one should even receive the vaccine. On the one hand are the government and medical authorities imploring everyone to receive the shot. On the other are various citizens concerned about the contents of the vaccine and its possible side effects. Unfortunately, this is a digital decision - 0 or 1. You either get the shot or you don't. You can't be a little bit pregnant, and if you are, congratulations: you're at the head of the line.

Confusion is poison in a document. It is the drop of oil in an otherwise pristine bottle of Perrier. It is to be avoided like the H1N1 plague. One way to inoculate your docs against it is to banish uncertain words such as: might, may, could, and perhaps.

For example: don't say:
Depending on your document type, some of the following tabs may not appear on the Properties dialog box.

Instead, explicitly state which tabs appear for each document type, for example:
For letter file types, the Main, Paper and Recipients tabs appear.

Certainly Uncertain

Even with this simple tip, you'll still encounter confusion and uncertainty when developing your docs. Often it's a case of one SME saying one thing, and another SME saying the exact opposite. If the issue is complex enough, the only solution is to lock both of them in a room together with you as the arbitrator, and not leave until the truth is found. (I've found faking flu symptoms and threatening to cough on both SMEs helps to quickly expedite the discussion.)

Sometimes the final answer you arrive at is different than what any of you envisioned. Those are the glorious moments in our profession. They validate our worth as information developers. They show we add real value to the company. And they give us a real shot in the arm.

Read More

The Doc Whisperer

I could certainly use dog trainer Cesar Millan. Our two-year old labradoodle Jessie is a bit of a mess. She often begs for food, and thinks nothing of resting on The Forbidden Couch. But compared to the dogs featured on Milan's show, The Dog Whisperer, she's Lassie.

The Dog Whisperer is a unique reality-TV program. In each episode, we're introduced to a new insane animal and its even more insane owners. Dogs with a wide variety of behavioral and disciplinary problems are featured. Before this show, I would never have believed a dog could have OCD (obsessive compulsive disorder).

Millan interviews the owners, then instructs them on how to deal with the dog's behaviour, using a combination of leadership, discipline and affection. The worst dogs are taken to Millan's Dog Psychology Center, where presumably the animal shares with a therapist its childhood problems and the fact it just "can't let go" of the doggie treats.

What's most impressive about Millan is how efficiently and professionally he interviews the owners, quickly assesses the situation, and in some cases, is able to immediately correct the problem. Dogs are often transformed right before the owner's eyes.

Dogs vs. Docs

A dog whisperer, therefore, is a trained professional who assesses the animal, interviews the owners, and provides a solution. The definition of a "doc whisperer" is self-evident, but a comparative list is helpful:

• dog whisperers assess dogs
• doc whisperers assess docs

• dog whisperers interview owners
• doc whisperers interview owners, including subject matter experts

• dog whisperers see what the problem is right away and recommend a solution
• doc whisperers do the same thing

• dog whisperers show leadership by implementing the solution
• doc whisperers - ditto

• dog whisperers follow up with the dog and its owners to ensure the solutions are maintained
• doc whisperers follow up with the doc and its owners to ensure the solutions are maintained

Doc whisperers are more commonly known as "senior technical writers", but what's in a name anyway? So if you want to be a great tech writer start whispering....

After all, dogs and docs are very similar: they both need lots of attention, they both can get out of control if not maintained, and they both involve toys, as in:

"Here Rover - it's the latest edition of FrameMaker, with tabbed browsing and better conditional text management."

"Arff!"

Read More

Tech Writing, From A to Wii

My wife asked me if we're ever going to buy a game console. In my worst French I mumble, "Oui". "We're getting a Wii!?!" she cries, " Woo-hoo!" I cannot Undo my misunderstood utterance.

The good news is that Nintendo recently lowered the price of its popular gaming unit. The bad news is that the unit represents only a fraction of the total price. Once you're done adding accessories (such as the Wii fitness board, extra controllers, other games, extended warranties and taxes, you end up with a purchase price approaching that of a small car. But, oh boy, is it worth it.

A brief disclaimer - neither I, nor any of my relatives, friends, or enemies work for Nintendo. However, I sure wish I did.

The Wii is a masterpiece of design, form and function. That's why it's outsold the Xbox 360 and PlayStation 3 combined. I don't even want to discuss the documentation that comes with Wii, which is adequate, but the fact that most users won't even need the guides. (Gulp! No tech writers needed?!)

The I's Have It

The Wii succeeds because it has the magic combination of I's:

• Intuitive - it's easy to use
• Informative - it gives clear and simple instructions as you're using it
• Intelligent - it appears to "learn" from your actions
• Incredible Interface - based on all of the above

A huge factor in the Wii's success is its simplicity. The remote only has a few buttons. The games, aimed mostly at families and non-power users, are generally simple to learn and play. That is, the user does not have to struggle with the hardware or software to learn it.

Am I Making Myself Clear?

Every professional communicator (including us technical ones) can learn from this. Readers should never have to struggle to find the information they're looking for, or understand the information you give them. It should be as clear as glass.

Beyond documentation, technical communicators have a critical role to play in product design. I'm fortunate to work for a company that actively solicits feedback from its employees, and have given numerous suggestions for enhancements to the user interface. No formal training is required for common sense suggestions, such as the fact that every field should have a name, and that the name should be clear and self-descriptive.

Always be on the hunt for superb design and execution, as seen with the Wii. It can inspire you to create great documentation.

Now, back to tennis and golf...

Read More

Catch the Wave

Outdated is a word coined by manufacturers to convince people the shiny new products they purchased six months ago and which work perfectly are now useless. However, once in a while, a new product comes along that really does make the current version practically obsolete. Google Wave could be just such an application.

Google Wave is difficult program to describe, but is essentially a cutting edge communication application that's a combination of email, instant messaging and collaborative editing. Because Google Wave is so different than anything before it, the best way to learn about it is to watch the long video here. The next best way is to finish reading this article.

New Wave Rocks

Google Wave is the name of the latest application developed by Google. Within it you create documents called, appropriately enough, Waves. Waves are XML-based document objects similar to an email thread, but so much more. Instead of writing and sending an email, you create a Wave and then share it with others.

Google Wave was created because email as we know it was developed long before the Internet, the World Wide Web, rich content and multimedia. Traditional email is like putting horseshoes on a Ferrari - painful.

Creature Features
Here are the main features of Google Wave that make it light-years beyond regular email:

• when you type a message, other users see your keystrokes in real-time, character by character; no more "Amy is typing..." messages to wait through, although you can turn off this feature if you wish
• instant and intelligent spellcheck: for example, "It's bean so long" is automatically corrected to "It's been so long"; "icland is an icland" is automatically changed to "Iceland is an island"; these changes are either instantly made, or suggestions are automatically presented in a drop-down list below the word in question
• you can view the history of a message thread using a "playback" feature - this allows you to step through each response as it was received, one message at a time, so you can see who wrote what and when they wrote it
• multiple users can update the original message - all users will see each other's changes in real time as they are typed, in other words, real-time live document colloboration
• a built-in search function - you can search sites, images, videos, and then with one click instantly add the link or photo to your message
• you can easily respond to just a portion of a section in the message, instead of the entire message; new threads are automatically created
• you can easily drag photos onto your message, and rename them, again in real time
• automatic recognition of URLs: if you enter google.com, it is instantly converted to a hyperlink
• you can easily embed videos

Extending a Hand

You can also extend Google Wave by creating extensions for other applications and websites. For example, you can:

• add a Wave to to a blog - updates to the Wave instantly appear in the blog, and vice versa, in real time
• add Twitter to a Wave - the Twitter thread appears in Wave - updates to one appear in the other
• embed various apps, such as a chess game
• create your own "branded" Wave; for example the ABC Company could create a Wave that appears as an ABC Wave, with all of the Google Wave's functionality
• add a "response" gadget - a table with multiple columns: each column represents a response to a question, for example: Do you like cheese? - Yes | No | Maybe; when you respond, your ID appears under the column of that response; to change your response, you simply click another column and your ID instantly moves to that column
• insert a map into a Wave - if one reader zooms in or out, or annotates the map with markup tools, the other users will instantly see the new view or the changes
• add a form: for example, multiple users can collaborate in real time on the construction of a poll; you can be writing the questions while another user writes the potential responses; you can then can instantly send out the poll to all the recipients, and the poll results are updated live in real-time

To Infinity and Beyond...

These features are indeed incredible. But perhaps the most outstanding feature of all is the one demonstrated near the end of the video: real time translation to another language. Using a special translation add-on, you can type in one language and an instant, real-time, word by word translation appears in another language.

When new technology like this comes along, I'm always reminded of two of Arthur C. Clarke's "Three Laws":

• The only way of discovering the limits of the possible is to venture a little way past them into the impossible.
• Any sufficiently advanced technology is indistinguishable from magic.

On the first law: Only by hiring the best and brightest engineers could Google create such an application. But technical intelligence only gets you so far; you have to be a dreamer, a doubter and a rebel. You must believe in the impossible to do the possible.

On the second law: Google Wave certainly does appear "magical". But we have to be careful not to be overwhelmed by the magic. Just because a new product can be used in new and different ways does not necessarily make it more "usable". I'm sure many of us could personally could benefit from such a tool, but we are hyper-combinations of communicators and engineers. Many people might balk at such a complex application. Just because something may be "better" doesn't mean people will use it. History is filled with "better" products that failed for other reasons: price, usability, inability of people to change - the Apple Newton and WebTV are but two examples; you can view more here.

The Wave is scheduled to be released either late 2009 or early 2010. It will be fascinating to see if it succeeds, because it could impact our profession. Think about it: XML-based; collaborative editing; ability to track changes; instant communication - are these not the ideals of technical communication? If the Wave takes off, it could inspire a whole new generation of people to become technical communicators.

And what a Wave that would be...

Read More

He Said/She Said

Here's a word puzzle for you: which pronoun (he or she) would you use to describe a person who has had a sex change? I ask this because I recently read a news article about a female teacher who underwent such an procedure. The teacher now considers himself?/herself? as a man. (Oy - I'm already running into trouble here.) However, the school (a religious one) still views this person as a woman. The author of the article used the title Mr. and the pronoun he when referring to the teacher. Is this correct?

You see the catch-22 here. By using the word he, the writer accepted the position of the teacher, and tacitly recognized the teacher as a man. But if the writer had used the female pronoun, he would have been considered disrespectful toward the teacher. What's a poor writer to do?

Mutant Hybrid
One solution is to create a new type of hybrid pronoun, something like s/he. Not only is this awkward, it has the side effect of offending both points of view. The solution lies the basic principle of technical communication: Know thy audience.

You see, this entire he/she debacle is not the problem: it's a symptom of a much larger problem: trying to write the same information for two different audiences, in a vain effort not to offend either. The two audiences are secular and religious.

Secular Vs. Religious
Let's assume that most people who read non-religious newspapers are secular. So we can safely take the liberal, secular position and assume that whatever someone calls themselves, they are that person. This relates to another aspect of information development.

In documentation, we sometimes have to describe different types of users: basic, intermediate, advanced, and so on. Many software applications will only allow certain functions or screens to be accessed by certain user types. For example, an Administrator will have access to certain modules that a Worker (a regular user) would not.

Who defines these roles? Well, ideally, the person who is working in that role would have to agree, at least on a general level, to that description. Heaven forbid we have a regular user calling themselves an Administrator. That is, the person filling the role helps define the role and needs to agree to the role they are assigned to.

Back to the story - the teacher views himself/herself as a man, and is legally recognized as a man in our secular legal system. So from the secular perspective he is a man. Therefore, the newspaper would be right to use he.

Now, if you are a deeply religious reader, you:
a) don't read secular newspapers

-or-

b) do read secular newspapers, with the understanding that they might "offend" you

-or-

c) read only religious newspapers

So if I was writing about this person for a religious magazine, I would use she, because that word reflects the religious viewpoint. Just as secular writers should not be forced into the religious viewpoint, religious writers should not be forced into the secular one.

That is the essence of documentation: writing with your audience in mind.

And you could easily single-source both articles in FrameMaker. God bless Adobe! (Oops...)

Read More

A fee by any other name

Rogers announced they're dropping the hated $6.95 cellphone system access fee. They're replacing it with a "regulatory recovery fee" ranging from $2.46 to $3.46. They're also raising their rates by $5. The net effect is that rates will increase between $.51 and $1.51. Rogers is also adding three non-optional calling features, in vain effort to minimize the wrath that will surely ensue. Talk about rate rage.

This is a scheme so brilliant it could only have been developed by a marketer in collusion with an accountant. To announce a lowering of fees when it is actually a fee increase is the finest example of double-speak.

It actually goes further than that. Why even list any separate fee? It's the same kind of deception and nonsense we see in car prices (with fees for freight and inspection) and airline tickets (with fees for security, landing, taking off, passenger facility, airport use, and god knows what else.)

The bottom line is that there should be only one bottom line. Only one number should be given for any price. (Well, one pre-tax number, anyway.)

Here's how I (or any sane tech writer) would have documented this change:

We are increasing our rates by $.51 to $1.51. To somewhat offset this, we'll now include three new calling features that regularly cost $11. As an additional goodwill gesture, we'll give you 100 free airtime minutes.

It's honest, it's clear and it respects the user; something all documentation should do.

Read More

Geek is the new chic

Check out this actual ad copy from a Best Buy flyer:

"We love love reading installation manuals so you don't have to. Connecting components, mounting TVs, dressing wires-Geek Squad is here to do all the work for you"

Ah - the geek squad - my true family. I mean, who doesn't love "connecting components, mounting TVS, and dressing wires. (What the heck is "dressing wires"? Do wires have pants?) In any case, we do love reading install guides. In fact, many of us got into this profession because we love reading guides so much, that when we read a poorly written one, we knew we could do better.

At least that's one of the geeky reasons I became I tech writer - what's your reason?

Read More

She loves docs, yeah, yeah, yeah...

My mother, who is from Liverpool, recalls regularly visiting the local record shop in the 1950's, owned by a gentleman named Brian Epstein. Epstein later went on to manage a rather well-known group called The Beatles. I'm reminded of this rather indirect claim to fame as I just finished watching The Beatles Anthology, a massive 10-hour, 5 DVD disk set, chronicling the history of the only group where everyone can easily name all its members.

The Beatles are again in the news, as their Rock Band game is set to release on September 9, 2009. The game allows players to follow the rise of the band and play along with them. Also, re-mastered versions of all their songs will be released the same day as the game. Ain't technology grand?

Now, Paperback Writer is one my favourite Beatles songs, if only for the fact it's not a corny love song. Some may say that most technical writers are simply frustrated authors, which is nonsense. Technical writing can be just as fulfilling a career as fictional writing, with the added bonus of actually getting paid. Also, in both professions, you can just make stuff up to please the reader.

And on that note, I offer my new and improved version of this classic song:

Technical Writer

Dear Mr. or Ms. Reviewer, will you read my doc?
It's got a twelve page index that really rocks
It's for an application that you'll never use
But I need this job, so I wanna be a technical writer,
Technical writer

When you read my guide, you'll join my many fans
It's got lots of screenshots and colour diagrams
It's got overviews and cool multi-step tasks
You see I have no life which is why I have to be a technical writer
Technical writer

It's got fifty-seven sections, give or take a few,
I'll be copy-editing more in a week or two.
I can give you PDF, Frame, Word or text,
I can even give you XML
because I'm a senior technical writer,
Technical writer

If you really like it, then please tell my boss
He ain't a tech writer and he's really lost
He has no idea what my my job entails
that's why it's so much fun to always play the technical writer,
Technical writer

Technical writer, technical writer... (repeat forever)

Read More

Driving For Fonts

A fellow tech writer sent me this interesting site: http://www.iqfont.com.

It's about a new font developed by Toyota for their latest car, the iQ, one in a series of impractical cube-shaped cars that include the Nissan Cube, the Kia Soul, and the Mini. Apparently, Toyota used the car itself to design the new font that goes with car. View the video to see how.

If cars can be used to develop fonts, what's next? Perhaps washing machines could create "clean fonts", steam irons could create "smooth fonts" and small children rolling around in mud could make "kiddie fonts". Ah, I can see it now - the next great font developed by computer tracking the paths created by small rodents. We'll call the new font - Rats.

Read More

TECHWRTR For Sale

If you're an experienced tech writer, you may be asked to do more than just tech writing. You may have to write documents which try to sell a product, documents such as Release Notes or other marketing material.

Writing to sell is therefore an important skill to have, but not just for work. It's handy when you are trying to sell something. On that note, I recently sold my 2001 Honda Civic, license plate: TECHWRTR.

Here's the actual ad copy I used on Craig's list and Kijiji, with my private info hidden to protect the innocent:

---

2001 Honda Civic LX

Contact Info

• Andrew Brooke
• 416 NNN-NNNN (home) or 416 NNN-NNNN (office)
• name@email.com

See pictures at:
http://website of pics

• Private sale - no GST.

General Features

• 4 door sedan
• 120,300 km: average of only 15,040 km/year
• automatic transmission
• air conditioning
• seats five comfortably
• beige exterior and interior
• 4 cylinder engine
• front-wheel drive
• body-side moulding
• original owner, non-smoker
• accident-free
• very well maintained
• very comfortable and spacious
• great on gas
• interior, exterior and engine all professionally cleaned

• rated "good bet" by Consumers Reports: "The Civic...has good crash-test results, handles well, and has outstanding reliability. A redesign for 2001 offered a bit more cabin space. It has a firm ride and relatively nimble handling."

Comfort & Convenience

• cruise control
• power windows
• power door locks
• power adjustable heated side mirrors
• driver and passenger vanity mirrors
• adjustable tilt steering wheel
• power assisted steering
• interior remote (lockable) trunk release
• interior remote fuel release
• 60/40 split fold-down rear seat for extra trunk storage
• no floor hump in rear passenger section, giving extra room in back
• 4 speaker digital AM/FM CD player (holds 1 CD) with clock and multiple station presets
• remote door lock/unlock (two remote openers included)
• two extra front cabin lights
• height-adjustable front headrests
• two front seat cup holders
• centre console storage compartment
• intermittent wipers
• digital odometer/trip meter
• plenty of door storage space
• adjustable console brightness
• large trunk with cargo light
• driver's side armrest
• accessory power socket
• rear window defrost and internal antenna
• ergonomic cloth seats

Safety Features

• driver and passenger side airbags
• ABS (anti-lock) brakes
• 3 month old tires
• anti-theft ignition (car cannot be started without the original programmable key)
• anti-theft radio
• rear door child-proof locks
• master power door lock
• master power window lock (locks all windows)

Extra Console Indicators

• tachometer
• automatic gear indicator on dashboard
• low fuel indicator
• low oil pressure indicator
• maintenance indicator
• low windshield washer fluid indicator
• seatbelt reminder indicator
• trunk open indicator

Maintenance & Testing

• all testing and oil change done July 27, 2009
• all service records included
• owner's manual and all other original documents from dealer
• call my mechanic, Mario DiLeo for more information about the maintenance of this car: 416 NNN-NNNN.

Required Documentation

These required documents are included at no extra cost:

• Ontario Used Vehicle Information Package: $20 cost - included
• Emissions test/Ontario DriveClean program: $37 cost - included
• Ontario safety certification: $95 cost - included

Other Included Items

• two master keys + one chauffeur key
• two keyless remotes with panic button
• mini-spare tire with jack
• touch-up paint
• original Honda cloth floor mats

Free Extras!

• four free beige rubber all-season floor mats
• black plastic trunk liner
• two free summer windshield fluid jugs
• free 2007 Perley's Toronto large print map book (like new!)
• free license plate covers
• free full tank of gas

Note: A cash deposit is required to purchase this car.

Ready to go - just buy and drive!

---

This is an ad only a tech writer could come up with. But it worked - I received many calls and had several showings. The car sold quickly because the ad was clear, concise, descriptive, and had lots of good photos. Plus, everyone loves a good Honda.

So, whether you're trying to sell a car or get the user to learn a product, all writing must cause the reader to do something. If it doesn't, then why are you writing?

Read More

Microwaveable Message

I'm annoyed with the writer who developed the message that appears on my microwave when it's finished cooking. The message is: ENJOY YOUR MEAL.

Maybe I'm not cooking a meal - maybe it's just a snack. Maybe I'm heating up a drink or a small, defenseless animal. Maybe I don't want to enjoy my meal. Besides - how can an appliance wish enjoyment on anyone? I thought only higher mammals could do that.

On top of all this, it takes an agonizing five seconds to display the message because it has to scroll the letters vertically and can display only about five letters at a time. Five seconds to a normal person is five hours to a tech writer.

If I'd been the tech writer on this job, here's the message I'd have written:

DONE

Now I'm done with this blog entry.

Read More

Michael J. vs. Mahmoud A.: A Study in Conflict

It's sure been a busy few weeks in the newsrooms. The sudden death of pop legend Michael Jackson was not only a media mega-event, it was an astute career move on his part, dramatically increasing his music sales; perhaps he should have died more often. (For those of you who thinking I'm being cold, sober up, and read this.)

What's astounding is how coverage of Jackson's death completely obliterated the other much more important event: the ongoing protests in Iran. Iran's population is 70 million - over twice that of Canada's. More people would be affected by a change in the Iranian government than by Jackson's death.

Twitter Twatter
I could talk about how these two stories are connected because they're both excellent examples of how new technologies such as Twitter and cell phone cameras allowed the news to spread so quickly. But plenty of techno talking heads have already observed this. What's more interesting to me is how these two stories are connected because they show the ultimate result of conflict: trying to mix two diametrically opposed ideas and obtain a successful result.

Mahmoud the Madman
Iran's conflict is obvious. Mahmoud Ahmadinejad, a delusional psychopath of a president, is trying to run the country as a "theocratic democracy", which makes as much sense as a 600 page "quick start guide". A state can be a theocracy or a democracy - it cannot be both. The protests arose as a direct result of this conflict. They would not have occurred if elections weren't allowed in the first place or if Iran was a real democracy. It is the conflict between these two ideas that caused all the ruckus.

Madman in the Mirror
Jackson's conflict is subtler, as it's the conflict within one person instead of an entire nation. Jackson was a brilliant and gifted musician, dancer and performer. The problem was that he thought this also made him a brilliant and gifted person, so much so that he raised himself to the status of a demi-god. His massive statutes and endless tributes to himself are ample proof of this.

Jacko thought he could do no wrong, and this included doing whatever he wanted to innocent children. You could say his downfall began November 16th, 2006, for on that date he was booed at the World Music Awards in England, and left the stage visibly shocked. The real world's view of Jackson had come crashing into Jackson's view of himself. Death through addiction was the ultimate conflict resolution.

Communication Conflicts
Conflicts like these, where two opposing entities try to occupy the same place, exist in our profession. They include non-technical communicators, primarily developers and marketers, pretending to be technical communicators.

A marketing technical communicator or a programmer technical communicator is as much of an oxymoron as Iran's theocratic democracy. The result can be a guide from the marketing department that constantly tells users how wonderful the product is and thanking them for purchasing it, without really telling them how to use it. Alternatively, if written by a programmer, the guide is hyper-technical, generally incomprehensible, and filled with such lovely phrases as: "Make sure the two modules play nicely with each other."

Internal Documentation
Of course, it's easy to make fun of marketers and developers, because that's what they're there for. Other conflicts involve us and the actual work we do. On the one hand, our profession demands that we are honest and open with our readers, and tell them what they need to know to use the thing we are documenting. On the other hand, there is pressure not to tell users every single problem that could occur in the product, lest we scare them off. An experienced technical communicator, working with the product manager, will steer the right path between these two opposing goals. It's a dirty job, but it sure beats working in a slaughterhouse.

A more serious conflict, akin to Jackon's internal conflict, is the one within some technical communicators who really should not be technical communicators. Maybe they've changed. Maybe they never really had a passion for words, clarity and the thrill of creating a complex table or a clear and succinct instruction. (I still love the smell of Visio in the morning.) Whatever the reason, communicators who are no longer interested in communicating had better find something else to do, because eventually, as with Michael and Mahmoud, the world will finally catch up with them.

Read More

Give Me Some Credit

People love their credit cards, and why not? A slim piece of plastic allows you to buy almost anything at any time; you don't even have to leave your home. There's just one small detail: eventually, you must pay it all back. And if you can't do this right away, the credit card companies are more than happy to oblige, and will lend you the money at an obscene interest rate.

Millions of people don't realize this, and simply pay the minimum balance because, hey, isn't it easier to pay $30 now rather than $1,000 now? Credit card companies love people who think like this.

Deadbeat, and Proud of It

I, on the other hand, along with my financially intelligent peers, am scrupulous about paying off the balance each month, in full. In addition, I pay no annual fee, and actually receive back 1% of everything I spend in free groceries. Over the years, this has added up to thousands of dollars.

Credit card companies hate me. They have an interesting name for people like me who pay their balance in full: deadbeats. We're deadbeats because we don't provide any extra income to these companies.

Now, however, the number of "deadbeats" may be increasing, thanks to recently proposed Canadian government legislation. It includes a minimum 21-day interest-free grace period on all new transactions when people pay their balance in full by the due date. The other two main changes involve documentation; that is, the infamous Credit Card Statement.

An Inconvenient Document

Under the new law, grace periods and interest rates would have to be clearly displayed in a summary box on the statement. That's important, but it's not the biggest change.


The biggest change is that the statement would clearly indicate how long it would take you to pay off your balance if you only made the minimum payments every month. It is this omission of a single, small piece of data from this document that has cause more grief, more financial suffering, and more debt than anything else.

Loan Shark, Inc.

For example, let's assume you have a $2,000 balance and the interest rate is 19% (a fairly common rate). If the minimum payment allowed is 3% of this balance, and you can only make this payment, then your monthly payments will be $60. It will take you a whopping 14.5 years to pay off this debt, and you'll pay an astounding $2,007.03 in interest, just over 100% of the entire amount you borrowed! (To try more numbers, use this calculator.)

How many people would have paid off their balances sooner if they had known this? Now you can begin to see why the banks fought against this legislation. They (and many lawyers) are the antithesis of our profession, because they wage war against the most cherished principle of technical communication:

Tell readers what they need to know to help them succeed.

Read More

The Matter of Dark Text

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.

Read More