Join the Bloc!

Related imageI survived the G20 riots. They happened near my former workplace in downtown Toronto; fortunately, our office had recently moved to the slightly more peaceful city of Markham. No one was surprised by the violence; it was all foreseen, based on the history of previous summits. Remember the “Battle in Seattle” in 1999? It’ll be difficult to name this current event, as there are few words that rhyme nicely with Toronto. Perhaps “The Scenario in Ontario”.

What exactly did the G20 summit produce? A non-binding document, in which, among other things, the various leaders pledge to reduce their outrageous spending. What happens to leaders who don’t meet their deficit reduction targets? Well, the other leaders might stare really, really hard at them, call them names, and maybe even start turning the lights on and off. Oh boy – that’ll scare them into fiscal responsibility.

Time for some post-mortem documentation analysis. The security costs alone for the summit were over a billion dollars. There are 10,500 words in the released communiqué. That works out to over $95,000 per word. However, the total cost is even higher when you factor:

  • transportation, food and housing for all 10,000 delegates
  • construction of all the venues, including the “fake lake”
  • the funky G20 logos and marketing
  • three slightly over-cooked police cars
  • damages to stores
  • lost business
  • court costs for the anarchists

When all these are added in, the cost per word easily exceeds $100,000, a handsome rate for any writer.

Here’s a few other random thoughts from this event:

Don’t want to be arrested? Read the manual!
Over 900 people were arrested during the summit – a new Toronto record – woo-hoo! Now, some of those arrested and detained were admittedly innocent; passers-by, onlookers and journalists. To avoid future errors, I recommend a Summit Safety Manual be issued to all residents of the next city fortunate enough to host the next G20 summit.

This manual will contain only one procedure:

Not Getting Arrested
If you do not wish to be unavoidably detained and arrested, and held for an unlimited number of hours without access to food, water and washroom facilities, please complete the following task:
  • Stay far away.

Sign, Sign, Everywhere A Sign
I enjoy reading the communication (a.k.a. signs) displayed by the protesters with such brilliant and pithy statements as:

  • Ban the G20!
  • Capitalism sucks!
  • Bury the bankers!
  • Nature doesn’t do bailouts!

The problem is that unlike a well-written document, the signs don’t tell the reader what to do. I therefore plan to show up at the next protest with the following sign:

  • Ensure your sign includes a clear, specific action for the reader!

Even if the signs had been clearer, as documents they are useless. The world leaders are the end users for these signs. Has there ever been an instance where these leaders have said: “Gee, this sign says ‘Ban the G20’. I guess we’d better cancel the meeting.” Clearly, the sign-writers have yet to learn the prime directive of technical communication: Know your audience.

A Paradox for Anarchists – Let’s Get Organized!
To call the anarchists who destroyed property idiots would be an insult to idiots everywhere. These thugs have the intelligence of blank hard drive. Now, there’s nothing wrong with a little bit of revolution now and then; many great nation-states were born from revolution. The difference, of course, is that these historical revolutionaries stood for something, whereas the anarchists stand for nothing, except, of course, more anarchy.

Technical communication is undergoing a revolution from:

  • traditional WYISWYG tools where the content and the design of information is done simultaneously, and the documents are typically stored locally and organized into chapters and books


  • server-based XML tools where the author works only with segments of pure text (no formatting), which are classified based on their type and which are stored on a central server that many authors can access

This is a colossal change; I am therefore launching a new movement named after the infamous Black Bloc G20 anarchists – it will be called The Text Bloc.

Join us as we smash old (computer) windows and destroy the old outdated documentation ways!

Chant with me now the following statements:

  • Death to WYISWYG! (Or at least partial harm to it!)
  • Paper-based systems don’t do bailouts (and they don’t do many other things either!)
  • Hey Mr. C.E.O. – can you spell X.M.L?!
  • Information wants to be free! (But avoid anthropomorphization!)

The Thrill of "Top Kill"

Image result for british petroleum logoBritish Petroleum (BP), responsible for the worst oil spill in U.S. history, should be given an award. Not for their oil drilling abilities (which one could fairly say are a tad below par), but on their naming abilities.

Specifically, whoever coined the term top kill to describe their latest failed effort to plug the ruptured oil line is a genius. It beautifully and succinctly describes an incredibly complex process.

Technical communicators are often asked to name things, specifically fields and other elements in a user interface. Giving objects clear, simple and self-descriptive names is often quite a challenge.

As an example, several months ago I reviewed the interface of a file migration utility. This application migrates files of one type into another. The interface consists of just one large dialog box. The user enter various parameters, then clicks a button to start the process. The question is: what should the button label be?

Initially, this button was simply labeled Go, but that’s not very self-descriptive, is it? Also, Go only has two letters, making the button rather small in stature. The label I suggested, and which was implemented, was: Start migration. It’s not as sexy as Top Kill, but it does the job.

The PowerPoint from Hell

General Stanley McChrystal, head of U.S. and NATO forces in Afghanistan, has provided a perfect example of how not to create document: a PowerPoint slide that purports to explain the U.S. military strategy in Afghanistan.

Related image

“When we understand that slide, we’ll have won the war,” General McChrystal said. In other words, never. This image is the worst example in history of spaghetti documentation.

Now, compare that monstrosity with a simple document created internationally renowned tax expert Dr. Alvin Rabushka at Stanford University.

Dr. Rabushka has proposed a 15% flat tax for Canada. This would collect the same amount of revenue that the government currently collects, without having to wade through multi-page, hyper-complicated tax form documents and software.

The good doctor even designed a form the size of a postcard that could be filled out in about five minutes.

It’s estimated this simple document could save Canadians $30 billion when you factor in:

  • the time and effort spent getting receipts and preparing tax returns
  • the cost to hire accountants and lawyers to sort through the massive tax code
  • the cost to employ vast armies of tax collectors their support staff

I can think of no two documents with more different content and results.

The PowerPoint explains nothing, saves no money and may even indirectly contribute to the war’s endless multi-billion dollar cost by giving the illusion of comprehension to an incomprehensible situation.

The tax form is clear, simple and explicit, and would save billions of dollars.

Which document would you prefer to manage?

The Tech Writer vs. The Volcano

Related imageAfter a week of chaos-inducing activity, the volcano in Iceland finally ran out steam, or in this case, lava and smoke. If a mountain could be arrested for causing a public disturbance, surely this one would qualify.

Fortunately in our profession, we don’t have to battle lava and smoke. However, we often have to clean up a mess. As smoke and ash cloud the air making it hard to see what’s out there, so do confusion, apathy and vagueness cloud up a document.

One of my company’s current projects is to rewrite an enormous documentation set. Some of the guides are several years old, and it shows. The documents were not always maintained, fogging up the truth, and hiding the important facts users need to know.

I am not certain of what would be the easier task: fixing the doc set, or getting a volcano to stop exploding.

Time will decide.

A healthy-sized document

Related imageThe Obama administration scored a major victory with the passage of its health care bill, a massive 2,000+ page document . I wonder if every Senator and Congressman has actually read the entire thing; a Quick Start Guide would be useful.

This bill sounds great in theory: millions of Americans who were not previously insured now will be. Insurance companies can no longer exclude people with pre-existing conditions, which from the horror stories I’ve heard could include symptoms such as “breathing” and “blinking”. Time will tell, though, if this bill will actually save lives. However, a new television show offers an enlightening perspective.

Jamie Oliver is a English celebrity chef who advocates healthy eating. He’s exposed and improved the quality of meals served in the English school system. In his latest show, Jamie Oliver’s Food Revolution, he visits Huntington, West Virginia, ranked as one of the the least healthy cities in the U.S. He is shocked to discover the high-sugar and high-fat processed junk being fed to schoolchildren twice each day.

Two scenes from this show will be forever etched in my memory. One is an experiment with some of the schoolchildren that goes horribly wrong. Jamie brings several young children into his kitchen-storefront. He takes out a chicken and shows them the good cuts of meat from it – the breasts, the thighs, and so on. What remains is the disgusting garbage leftover – the bones, cartilage and fat. He places these horrid leftovers into a blender, liquifies them, and adds artificial flavours and fillers, makes them into patties and deep fries them, to demonstrate how chicken nuggets are actually made.

At this point, Jamie asks the children if they would like to eat these nuggets, fully expecting that none of them will. To his shock, the children ask to eat them! Why? Because they are hungry.

In an even more disturbing segment, Jamie visits a classroom. He discovers that the children cannot identify basic vegetables such as tomatoes, potatoes and cauliflower. They can identify ketchup, french fries and hamburgers but have no idea as to where these items come from. In a later follow-up visit, the children have learned to identify the vegetables, but I’ve no doubt that this ignorance is common throughout the country.

Returning to the health care bill – the problem is that this bill does not directly address what is really killing and maiming Americans by the millions: poor diet, lack of exercise, and mental health issues including addictions such as smoking and drinking. This bill treats the symptoms of poor health, not the major causes or reasons.

It’s important to be aware of symptoms vs. underlying reasons in our profession. It’s a common perception that the purpose of technical communication is to instruct users on how to use a product or service. Although this is true, it is not the true reason, for we can always ask: Why do companies care if their clients can use the product? They care because if users can’t use the product, they will either return it or call tech support, both of which drain profits. However, even that is not the true reason.

For the true reason, we need to understand that all belief systems have definitions of good and evil. In the free-market capitalist system, the definitions are:

  • good – anything that increases profits
  • evil – anything that decreases profits

Now we have the real reason, and not the “symptom” behind the need for technical communication. It’s not to tell users how to use products, or to lower support costs, even though both these things are important. It is to maximize profits.

This is also the true reason because we cannot effectively ask “Why do companies need to maximize profits?” They just do.

Remember this in an interview. Technical communicators already are a disadvantaged minority, because we are a cost centre and not a revenue generator. Therefore, in a interview, you must show how you increased profits by decreasing costs.

Be good; don’t be evil.

Size doesn’t matter

Related imageThe Canadian government recently released over 2,500 pages of documentation. This was in response to pressure from the opposition parties regarding the controversy over how Afghan detainees were treated by the Canadian military.

2,500 pages sounds like a huge amount. The problem is that most of it was censored for “security” reasons, an explanation which the opposition, of course, does not accept. My first reaction when I saw the heavily-blacked out copies on the news was that it was a huge waste of toner and paper. The government could have spared themselves much grief, ink and trees if they had simply emailed everyone a document that only contained the non-redacted text.

Tech writers often get hung up size. Picture this conversation:

Tech Writer A: I’m working on a guide that’s 300 pages!

Tech Writer B: That’s nothing – I’m working on a guide that’s 1,000 pages!

Tech Writer C: 1,000 pages? That’s a lot – if you’re a little girl…

Size just doesn’t matter. The quality of a document is not proportional to its volume. Some shorter documents are useful while other larger ones are not. In fact, less is often more. Succinctness and brevity while remaining clear and thorough are the true hallmarks of quality.

No sex please, I’m neutral

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

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

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

A few points on this rather delicate topic.

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

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

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

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

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

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

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

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

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

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

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

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

When mail merges go bad

Related image697 former Parliament employees received a T4 tax form that belonged to somebody else.

Government House leader Jay Hill said the mixup probably happened when the employee lists were incorrectly merged with other addresses.

Responding to this documentation crisis, here is Mr. Hill’s quote of the day:

“I often wonder when people sit and stare at these computer screens all day why there aren’t a lot more errors like this.”

Time to take a break from this screen, I think.


Image result for BlockbusterBlockbuster Video is going bust. Although they have not officially filed for bankruptcy, it seems certain they will soon have no choice. This comes as no surprise, of course. The very idea of driving to a store to rent a movie is as outdated as a typewriter or Windows 3.1.

People today get their movies through mail rental services, downloading (legal and otherwise), video on demand and even vending machines. The funny thing is that Blockbuster offers these alternate services, yet is still going broke. Why? Because most of its customers are simply not aware of these services, allowing other companies to corner the market.

Lack of awareness is a big problem for our profession. Users don’t know how to use products because the users are unaware. If helpful documentation is available, users don’t know it. If users do know that documentation is available, they don’t know how to find it. If users can find it, they don’t know how to effectively use it. And even if the users do know how to use the document, the document itself may lack awareness if it does not clearly explain what the user is looking for.

As a result of all this ignorance, many working products are returned to stores because the users could not figure them out. The goal, therefore, should be to create visible, usable documentation. Otherwise, you will get busted.

Security breach!

It’s always entertaining to read about non-lethal lapses in security at a major event. Remember the debacle at the 2010 Winter Olympics? A man with false ID got within a few yards of U.S. Vice President Joe Biden before being arrested at the opening ceremony. You’d figure after spending almost a billion dollars on security, the organizers would be able to hire people who could spot phony passes. (I also wonder if the intruder got a refund, because, hey, opening ceremony tickets are expensive!)

Another security breach also involved the White House, where an uninvited couple crashed a State dinner, and actually met the President and Vice President. Security officials admitted there was a breach but said not to worry; the couple didn’t have any weapons. Gee, that’s a relief…

These incidents are actually symptoms of a much larger debate: balancing security with democracy. This has been a problem for society long before terrorists or 9-11, however modern terrorism has made the balancing act much more difficult.

On the one hand, governments have a responsibility to stop attacks and ensure their citizens are protected. On the other hand, they have to ensure they don’t turn their nations into police states.

On a more personal level, regular people face the “security vs. freedom” question. Having a credit card is convenient, but can expose you to fraud. Driving a car gives you mobility, but you run the risk of death or dismemberment. Every day, we’re always making trade-offs between safety and convenience.

Technical communicators are no different. One of the most difficult tasks in our profession is deciding what information to give to users, and what to withhold. Make no mistake – it is often in the user’s best interest not to tell them everything possible about the product you are documenting.

For example, you may be documenting a web-based product which has a particular task that can be reversed or “undone”. However, you may want to withhold that information, because by telling the user they can “undo” one function, they may assume they can undo other tasks, leading to disaster.

Another example relates to FrameMaker. If I were documenting this product, I would probably not tell users that they can:

  • combine conditional text conditions
  • include text insets within insets

because either of these actions actually creates further problems.

However, there is something much more valuable that the security debate teaches us: the importance of proper information gathering. 9-11 was a failure to properly gather, consolidate and evaluate information. The right questions were not asked of the right people.

Contrast that failure with how an Israeli security agent questioned Ann-Marie Doreen Murphy, a 32 year-old Irish woman who was trying to board an El Al flight to Jerusalem in 1986.

The conversation went something like this:

Agent: Did you pack your bags yourself?


Agent: What is the purpose of your trip to Israel?

Murphy: For a vacation.

Agent: Are you married?

Murphy: No.

Agent: Traveling alone?

Murphy: Yes.

Agent: Is this your first trip abroad?

Murphy: Yes.

Agent: Do you have relatives in Israel?

Murphy: No.

Agent: Are you going to meet someone in Israel?

Murphy: No.

Agent: Has your vacation been planned for a long time?

Murphy: No.

Agent: Where will you stay while you’re in Israel?

Murphy: The Tel Aviv Hilton.

Agent: How much money do you have with you?

Agent: Fifty pounds.
(Note: This is less than what a single night at the Hilton cost.)

Agent: Do you have a credit card?

Murphy: Yes.

However, she did not; instead, she showed the agent an ID for cashing cheques.

The agent sent her bag for additional inspection. A bomb was discovered hidden in her bag. Her lover had planted the bomb, unbeknowst to her. (Something tells me they’re probably not still a couple.)

Note that the bomb was discovered without any technical devices or sophisticated electronics . The agent simply used proper interviewing and behavioural observational techniques to discover the truth.

This is precisely what technical communicators need to do. Fancy documentation tools are nice, but they are no substitute for intelligent investigation.

When researching a document, you may have a conversation like this with a SME:

Writer: Is X true?
(where X is any statement of fact about the product you are trying to document)

SME: Oh yes, absolutely X is true.

Writer: Is it true all the time and under all circumstances?
SME: Uh yes, I think so. I’m pretty sure it is.

Writer: Well, what about in situation Y, or if you were to do task Z to get to X?
SME: Actually, in those cases, X is not true.

Writer: Thank you.

This happens all the time. It’s not that SMEs are stupid or don’t want us to do our jobs – it’s that they are trapped in their world of code and are often not able to see beyond it. They often lack the holistic, big-picture view that technical communicators must have in order to successfully document a product.

People who are studying technical communication in school should also take courses in detective work and investigative journalism, because all tech writers are really detectives and reporters.