Meet the new boss, same as the old boss

Mr. Mubarak is updating his resume. After 30 years in power, he was fired after 17 days of massive protests in Egypy. Apparently, his end users weren’t too happy with how he ran the country.

The populace is celebrating the “new Egypt”, but this could very well turn out to be the vapourware of the century. The new boss, Omar Suleiman, worked for the old boss, so it’s difficult to see how things will actually change. This isn’t Egypt 2.0, but more like Egypt 0.0 with some patches.

Moving on to actual software, many technical communicators detest the tools and systems that they work with. It’s tempting to simply revolt and dump the current process, replacing it with anything else.

However, any new tool or system must be viewed with its final result in mind. The two primary questions to ask are:

1. Will it improve the quality and efficiency of the information development process?
2. Will it improve the quality of the documentation itself?

If not, then as poor as the current system is, at least it works.

Whether changing a country or a process, we must remember George Orwell. His classic novel Animal Farm wonderfully documents the failure of the Russian revolution. The men represent the brutal Czarist government; the pigs are the communists. The men are overthrown by the pigs, who turn out to be just as brutal.

The final words of Animal Farm are the most haunting:

“No question, now, what had happened to the faces of the pigs. The creatures outside looked from pig to man, and from man to pig, and from pig to man again; but already it was impossible to say which was which.”

Help! My documents are leaking!

Image result for WikiLeaksThe world has been gripped by one of the sexiest documentation events in history: the release of thousands of sensitive (and very embarrassing) diplomatic cables by WikiLeaks. If there was ever any doubt about the absolute power of information, it can be laid to rest now.

The “documentation manager” of this mess, Julian Assange, is now under arrest, not for leaking classified information, but for sex crimes. This is because sex crimes are sexier than informational crimes.

This event has graphically highlighted the two types of information that we deal with: internal and external. Any information developer who gets these mixed up will run into a world of pain. The problem is that because most information is stored in a “soft” format (on the computer or the web), it is easier than ever for private information to morph into public.

A fool learns from their own mistakes; a wise person learns from the mistakes of others. Let’s learn from this and remember: any private information that you create can easily become public information. Thousands of examples of this happen every day including:

  • damaging emails accidentally sent to the wrong people, or deliberately forwarded to those people, or worst of all, made public (think Climategate)
  • error messages that were not properly reviewed and contain internal comments such as: tell the user not to be so dumb
  • any internal document leaked to the public

Therefore, any information you create or manage should include the following warning:


Censoring the census

Related imageIt’s a slow month in politics when the current burning issue for the Canadian government is a form document that no-one enjoys completing.

The government is in trouble because of their plans to scrap the mandatory 40-page long version of the census. It would be replaced by a shorter, voluntary version. Opposition parties, statisticians, researchers, and other groups say this will result in unreliable data being collected.

The government argues it’s wrong to threaten fines and jail time for failing to fill out the census, and that the long form was too intrusive, with too many personal questions.

The government has a point. Look at some of the information required in the long form census:

  • the languages you speak at home
  • your race, nationality, and religion
  • where you work and how get there
  • the language you use on the job
  • how much housework you do
  • how much time you spend playing with your kids or talking to your parents
  • whether you have trouble walking, climbing stairs, or bending
  • who pays the rent or mortgage
  • how many rooms and bathrooms in your home
  • whether your home has any “missing or loose floor tiles,” “defective steps” or more major deficiencies like “defective plumbing”

Does the government really need all this information? Although it’s important for governments to plan for the future, I doubt all these excessive, personal details are really required. But that’s not my main complaint.

The real problem is that I don’t see why this document (either the long or short version) is even needed.

The entire system of mailing out a paper document to millions of people, having them mail it back, then having thousands of workers manually place the completed forms into a machine that can read them is nonsense.

I’m not suggesting that all this information should just be entered online. Aside from the fact that this assumes everyone has Internet access, this would still be a flawed process because:

  • it requires people to complete a form, which introduces errors
  • the data is only entered every few years, meaning it is never up-to-date

The real solution would be to glean the information on a continual basis in real-time from existing government databases. Everyone in Canada already has an ID number: a SIN, or Social Insurance Number. This number already contains much information about you. The government could use this information on a continual basis, in both short and long term planning.

Such a system would actively pull the required information, without forcing citizens to enter it, and would always be current. Yes, it would be an invasion of privacy, but so is the census itself. If you’re going to invade everyone’s privacy, you might as well do it cheaply and efficiently.

If the government ever created a system, they would simply be following the best practices of modern information management systems. In these systems, manuals are not just issued every few months when there is a release. They are continually updated, regenerated and then posted online. This allows the end user to always have access to the most current version.

It’s time to move all paper-based forms to the ash heap of history where they belong.

Census designers – I hate those guys…

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!)

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.

Colour my worries away…

Image result for Homeland Security colour-coded advisory system.I love the simplicity of the Homeland Security colour-coded advisory system.

This system, which purports to indicate the threat of a terrorist attack, and thereby tells the general public how much they need to worry, is as follows:

  • Green – Low
  • Blue – Guarded
  • Yellow – Elevated
  • Orange – High
  • Red – Severe

(I didn’t list Yellow in its colour because the lack of contrast makes it hard to read – I learned that in college.)

Rephrasing this in practical terms (which is what information developers do), we get:

  • Green – Relax! Take a load off. No worries here.
  • Blue – Start getting a little anxious.
  • Yellow – Be afraid. Be very afraid.
  • Orange – Begin making your final arrangements.
  • Red – Stop reading this – you’re most likely dead already.

This list could be simplified to the last three colors (yellow, orange and red), because it is doubtful the U.S. government will ever set the level to Green or Blue. This helps keep everyone in a general state of panic.

We need a similar warning system for all public, distributed information. It would be as follows:

  • Green – This document is 100% complete and accurate. And it’s also fun to read!
  • Blue – Unless this document is describing something that could hurt or maim you, you can safely refer to it.
  • Yellow – This document contains quite a few errors and omissions that we just couldn’t bother fixing. Sorry about that. Proceed with caution.
  • Orange – Oh boy – this document has alot of problems. Missing procedures and overviews. Tasks that you can’t complete. A rotten index. I would stay away if I were you.
  • Red – Don’t even bother reading this. Ask your tech friend for help.

As an example, this entire blog could be classified as bluish-green.

An Echo from History

Related imageOne 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 in 1985.

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. Thousands of men were lost 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 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….