Are you really a tech writer? Take this quiz!

Perhaps you're just starting out in this profession and are not completely sure if it's for you. Maybe you've been a tech writer for many years and it just doesn't have the same romance that it did when you started. Maybe you have nothing better to do with your time than read insane articles like these.

Whatever the case, here is a foolproof quiz that will determine, once and for all, whether you really are a technical writer, or just a pale imitation of one.

Answer each question carefully. Tally up your score, and the truth will be revealed.

Note: For some questions, more than one answer may be correct!

1. A technical writer is someone who:
a) creates documentation that people actually use
b) is dead sexy and brilliant beyond compare
c) makes the world's third best tuna sandwiches

2. If I see a typo on a restaurant menu, I:
a) politely indicate it to the manager
b) am so upset I can't eat for two whole minutes
c) burn the restaurant down

3. The personal documents I've created include:
a) a written last will and testament
b) a written mission statement
c) documents that document the documentation process of the above documents

4. Adobe is:
a) a large software corporation
b) a member of the axis of evil
c) one of the lost Indian tribes, the others being Apache and Ojibwa

5. FrameMaker is:
a) a tool for creating solid documents
b) a tool for framing innocent people
c) proof that Adobe developers regularly smoke crack

6. PDF stands for:
a) Portable Document Format
b) Pretty Dumb File
c) Pathetically Dreadful Fonts

7. Thorough knowledge of English is important because:
a) English has many complex rules and subtleties
b) it is spoken throughout the world
c) I speaka tree languages – English da best

8. A CMS is a:
a) Content Management System
b) Crappy Management Study
c) Cultivated Management Seepage

9. Software developers are:
a) brilliant engineers
b) sometimes challenging to relate to
c) people who missed the Mother Ship back to their planet

10. Microsoft Word is:
a) a common word processing tool
b) the afterthought of a word processing tool
c) proof that Bill Gates is the anti-christ

11. Extreme documentation is:
a) a process in which documentation is created in a rapid, iterative fashion
b) a good name for a reality TV show
c) a process in which reviewers are beaten senseless for two to three hours if they don't review the drafts

12. XML stands for:
a) eXtensible Markup Language
b) eXtremely Manic Linguist
c) X-rated Martian Lovetoy

13. GIF, JPEG and TIFF are:
a) the names of image file formats
b) the names of my pet dogs
c) the names of my first three children

Here are the points rewarded for each answer: you'll get bonus points if you selected more than one right answer!
1. a) 1 b) 2 c) 0
2. a) 1 b) 2 c) 3
3. a) 1 b) 2 c) 5
4. a) 1 b) 2 c) 0
5. a) 1 b) 0 c) 3
6. a) 1 b) 0 c) 0
7. a) 1 b) 1 c) -5
8. a) 1 b) 0 c) 0
9. a) 1 b) 2 c) 3
10. a) 1 b) 2 c) 3
11. a) 1 b) 2 c) 3
12. a) 1 b) 0 c) 0
13. a) 1 b) 2 c) 5

Tally up your score. The maximum score is 56.

Here's what the scores mean:

40-56 – Congratulations! You have the soul of a technical writer. Other tech writers will beat a path to your door, and then beat you when they see how brilliant you are.

25-39 – You have the potential to be a tech writer. Start hanging out with other technical writers and annoying them with your questions, and you'll be one of us in no time.

Less than 25 – I hear there are some job openings in social work and horse whispering.

Read More

The Rescuer Professional

There’s a breed of reality TV that is particularly interesting: the “professional improvement” shows. These include home improvement and self-improvement programmes, but the theme is the same: professionals evaluate a person or thing (or sometimes both) and make dramatic improvements.

Why are these shows so popular? Is it really so compelling to see a house torn down and rebuilt, or a person getting a fashion makeover? Some say it’s so that we can learn to make similar changes in our lives, but I doubt I’ll be rebuilding my house or getting plastic surgery any time soon. (Besides, if you’re nose is too big, you can always make the rest of your face larger.)

Help - I Need Somebody!

I think these shows are popular because deep down, we all want to be helped by others who we think know better than us. As much as we strive to be independent, the idea of a professional arriving into our lives, giving us expert advice and then working to make the necessary changes is very appealing. It means less work for us and absolves us of the responsibility of doing it ourselves.

The experts who are on these shows are therefore not just professionals, but rescuers, or rescuer professionals. Rescuer professionals are not professional rescuers, the people who rescue the lives of others for a living: the firemen, paramedics, emergency room doctors, secret agents and late night hair stylists. The rescuer professional is someone who deals with non-life threatening situations in a calm, authoritative and professional manner, and who gets the job done right.

Woody and the Wolf

There’s great examples of rescuer professionals in the movies. In Toy Story 2, a toy repairman nicknamed “The Cleaner” skillfully repairs Woody, the main toy character. On a slightly more violent level, in the classic cult film Pulp Fiction, Harvey Keitel plays Winston 'The Wolf' Wolfe, the consummate rescuer professional, when he’s assigned to help gangsters get rid of a dead body and gets the gangsters to clean up the car it came in. (This inspired one of the greatest lines in film history, with one of the gangsters exclaiming: “You’re the [one] who should be on brain detail!”)

The question I come across the most in our profession is “How can I get the job at an interview?” The next most common question is “How do I keep the job I’ve got?” The answer to both questions is the same: be a rescuer professional.

Ordering: One Interview, Please

In an interview, you need to give the impression that things were not too peachy in the documentation department before you came along. You need to imply that there was little or no documentation process, that the docs were 42 years out of date and used 127 different fonts, that anarchy ruled, with hell, fire and brimstone raining down each day, with dogs and cats living together and issuing drafts; in short, that it was total chaos.

You were the rescuer professional. You brought order to the chaos. You cleaned up the templates. You created a style guide and perhaps a practices and procedures guide. You got the writers working together. You got the documents to look like they were created by one writer, and not by Sybil, with her various personalities.

You don’t want to appear arrogant, of course. You need to say it was part of team effort, but still show that you did these things on your own initiative without being asked.

And if you want to keep your job? Sorry – the only guarantees in life are death and taxes. You may be able to escape the latter if you’re richer than God; the former if you’re God himself. No job is guaranteed. The most you can do is lower the probability of you being laid off today. Don't worry about tomorrow, for it is a day whose time has not yet come.

What Have You Done For Me Lately?

At work, we must be the rescuer professionals. Ask yourself: What are you doing to further improve things? Oh yes, everyone is just so very impressed with how you turned water into wine, and made the drafts sing and dance yesterday, but what have you done today?

Do you have short, mid-range and long terms goals for your work? Are you making the time to investigate newer tools and technologies? Are you getting out of your comfort zone and working with things other than user guides, such as training materials, release notes, error messages, user interface elements, and even the names of code elements such as XML tags and class names? The more pies you can stick your fingers into, the lower the chance the company will put a pie in your face and discard you in the pie-heap of history.

Excuse Me - Do You Have the Time?

If you have the time to do these things without jeopardizing your deliverables, you need to do them. And if you don’t have the time to do these things, then that itself could be a sign of a bigger problem. The best jobs are ones which allow you the time to grow in them. If you’re not growing, and others are, where will that leave you in five years, in ten years, and beyond?

To win jobs and keep them, be the rescuer professional. Be the one willing to step into the fire to rescue the documentation dog. Be Extreme Makeover – Documentation Edition.

Read More

Arts and Sciences

I’ve always felt a funny feeling in my stomach whenever I’ve heard the expression “technical communication is an art and a science”, and it has nothing to do with the large corned beef sandwich I ate three days ago and am still digesting. It’s because there’s something about this expression that, although true, is meaningless.

The first clue that there’s something wrong is that you could apply it to almost any field:

Selling is an art and a science.
Teaching is an art and a science.
Business is an art and a science.

If so many professions, indeed if all professions, are both an art and a science, then does it really makes sense to single out ours? The problem runs deeper than this, though. What exactly does it mean when we say something is an art or a science? Could they, in fact, be two sides of the same coin?

I Feel the Need, the Need for Extreme

To explore this, we need to be extremist. What is the most extremely artistic profession you can think of? How about, oh, an artist?

Of course, there’s many different kinds of artists, but when I envision one, I see a French painter wearing one of those annoying puffy blue hats, and having consumed enough alcohol to knock out a small horse. (It’s a good thing I can keep my imagination in check.)

A painter certainly certainly needs to be artistic, so it’s self-evident that art is an art. Artists have to be creative, inspired, and imaginative. They have to be non-scientific and see things in an emotional, spiritual, and meta-physical way. Artists are often extremely emotional, sensitive and irrational; it’s no wonder that many of them abuse drugs, are depressed and leave this world all too soon.

Science has shown that the mind actually expends energy filtering out much of what we sense so that we don’t become overwhelmed. Artists seem to have a malfunctioning filtering system that lets in everything pour in. As a result, artists create great art, but have a nasty habit of killing themselves, which does not look too good on a resumé.

The Art of the Deal

But is art only an art? Look at the other areas that a successful artist needs to know. They have to learn about composition, colour, light, paints, brushes, and canvasses. They need to study techniques, styles, media, forms and textures. They should learn about the lives and history of other artists and artistic eras. And if they actually want to make a living as an artist, they had better learn the business of art: the gallery system, the curators and critics, and the art journal editors and writers. They must learn how to develop, schedule, package and present showings, and deal with those pesky clients. These things are not art, but the fact-based technical side of art – the science of art. Therefore, art itself is both an art and a science.

She Blinded Me With Science

Science, of course, requires enormous technical, scientific and mathematical knowledge. It requires a cold, hard analytical view of the facts, with no emotion. It requires observation and testing of readily available data. It’s not very artistic - or is it?

When Newton saw an apple drop, he “discovered” gravity. Edwin Hubble, using creative experiments, proved that the universe was expanding. Einstein, perhaps the greatest scientist of the modern area, would imagine himself riding a beam of light, and from that was able to envision his Theory of Relativity.

To say that science does not require innovative, creative thought is nonsense. A scientist who is not creative will never be able to discover new things. That’s why the history of science is one in which one model of reality being replaced with a newer one, until that one is itself replaced. Science, therefore, is also an art.

The New Math: Art = Science

If science is an art and a science, and art is an art and a science, where does that leave our profession? Right where we started, as both an art and a science.

It’s a science because it requires:

• knowledge of the technical subjects we document
• knowledge of technical tools
• the ability to analyze technical requirements and create complex, technical documents
• the ability to plan, organize, schedule, monitor and deliver projects on time

But technical communication is also an art because it requires the ability to:

• imagine yourself as the end user to try to predict their information needs
• creatively reword and organize information so that it is simple to understand and easy to find
• develop creative solutions to complex documentation problems
• work with others in a friendly, constructive, emotionally intelligent way

Technical communication: It’s an art. It’s a science. It’s a scientific art and an artistic science.
It’s both.

Read More

Publishing for Pollard

Most of you probably have never heard of Jonathan Pollard, the American who has been languishing in prison since November 21, 1985, almost 22 years.

Pollard was a civilian Naval analyst who discovered information critical to Israel's security was being withheld from Israel, even though Israel was legally entitled to it. This information included dangerous war capabilities being developed by Israel's enemies, as well as plans for terrorist attacks.

Pollard, knowing that lives were at risk, did all he could to have the flow of information restored, but with no success. As a result, he decided to pass the information to Israel directly, and was later caught.

Pollard had no trial but instead entered into a plea agreement with the U.S. government. In exchange for pleading guilty and fully cooperating, Pollard was assured he would not receive a life sentence. In perhaps the most brazen violation of an agreement in U.S. legal history, the government broke its promise and gave him a life sentence anyway, and a recommendation that he never be paroled!

The Big Lies

Two of the biggest lies you hear about this case are:
a) Pollard spied for money
and
b) Pollard was a traitor

The facts are this: Pollard spied to save lives; not for money. He actually went into debt to cover his expenses! Even the sentencing judge recognized money was not the motivation behind Pollard's actions, and did not fine him as is usually done for mercenaries.

As for the traitor lable: remember the first rule of information development: define your terms carefully. Treason is clearly defined in American law as giving aid and comfort to an enemy; to an enemy, not a friend, and last I checked, Israel and the U.S. were allies. That's why Pollard was never charged with treason but instead with one count of passing information to an ally.

A Grossly Disproportionate Sentence

What Pollard did was wrong, and he readily admits that. But the bottom line is this: the average sentence for Pollard's crime is two to four years and he will soon be entering the twenty-third year of a life sentence with no end in sight.

What is particularly unfair is that there are many people, who, unlike Pollard, are real traitors who gave critical information to enemy states, who received lighter sentences! By any objective measure, Pollard's life sentence is one of the greatest miscarriages in U.S. judicial history.

Meeting History

When Pollard was captured in 1985, I was 19 and starting my second year of college. Around that time, I saw an interview of Pollard on 60 Minutes, and thought it was a tragic case, but that there was nothing that I could do about it. Little did I know that our paths would cross years later.

Fast forward to 1995: Jean Chretien was into the second year of his first term. Bill Clinton was in the White House. Windows 95 had been released, and the Internet was just taking off. I was working for an educational organization doing assorted computer work and managing databases. And out of the blue, I was invited to attend a local Jewish discussion group, where Esther Pollard, Jonathan Pollard's wife (who lived in Toronto), was speaking. Her sister was actually a friend of my wife.

I remember Esther's presentation as if it were yesterday - it was absolutely riveting. I was shocked beyond belief that such a thing could happen in a democracy. After the presentation, Esther's sister introduced me to Esther.

I asked Esther, very naively, if any organization or group had set up a website for her. I later learned that all of the groups you think would have been helping (religious and human rights groups, as well as the Israeli government) had, in fact, done nothing, and in most cases, actually hindered all efforts to get justice. This was the beginning of my "education" on the case.

The Truth is Launched

I offered Esther my help, and she told me I was one of two people who might be able to help out and that she would contact me later if needed. The other person fell though, so, in 1995, we launched the Justice for Jonathan Pollard website, and the rest is history.

What started out as a handful of items has grown into an enormous encyclopedia of news articles, legal documents, letters, photographs, audio and video files and political cartoons. There are thousands of pages of material, and it would take months to read it all.

As my information development and technical skills improved, so did the website. In fact, it's because of the website that my skills have improved! When you are dealing with a man's life, you can't afford to make mistakes. The information has to be clear and easily understood.

Paying it Forward

Looking back over the last twelve years, I'm truly amazed to be involved in this effort, and am very proud and privileged that I'm helping in some way. All information developers, indeed all workers no matter what their profession, need to find a cause outside of work and apply their talents to it.

There are so many groups and charities that need your help with their information; with their websites, newsletters, emails and so on. Find something that you are passionate about and offer your services. It's great experience, you may get to try things you normally wouldn't because you are doing it for free, and most importantly, it's the right thing to do.

We are where we are today because of the help and support others gave us. The best way to pay this back is to "pay it forward" and help others. Who knows? You may even save a life.

Read More

Snakes on a User Guide

"Snakes on a Plane? What's that about?"
From the Dilbert Newsletter

I just finished watching the awesome action film, Snakes on a Plane. Only a technical writer could have come up with such a self-descriptive title. It ranks right up with The 40 Year Old Virgin, Silent Movie and Robin Hood: Men in Tights. Can you imagine what other films would have been called had this explicitly self-descriptive technique been applied? Here's a partial list:

• Titanic - A Very Big Ship Hits A Very Big Iceberg; Hundreds Die
• The Godfather - A Whole Lotta Italians and Others Get Whacked
• Harry Potter - Good Wizards Fight Really, Really, Evil Guys
• Star Wars - Many Spaceships Chase Each Other and Blow Up Real Good
• Lord of the Rings - A Bunch of Extremely Annoying Creatures Go Chasing After a Stupid Ring
• Shrek - Funny, Big, Green, Scottish Ogre Rescues a Princess
• Jaws - Not So Funny Big Shark Eats Various People

Somehow, I don't think these films would have done as well. In any case, Snakes on a Plane is an excellent example of how user feedback can be effectively incorporated into the main product. The film generated so much Internet buzz that the producers reshot the film, making it more violent and explicit, causing the film's rating to be changed from PG to R. Rather than suing all the fans who created websites and blogged about the film, the film industry actually embraced the fans and updated the film based on their feedback.

Not only was this an absolutely unprecedented way of producing a film, it is a model for the way documentation should be created and reviewed. Select clients and power users should be allowed to see early drafts of our documentation, so that they can suggest changes. This is often done for the actual software - why not documentation? Then we'd no longer have to scream, paraphrasing from the movie:

Get these mother-****ing errors out of my mother-****ing draft!

Read More

The Four I’s of the Perfect Storm

The Perfect Storm was the name given to a group of three independent weather systems that converged to create a hurricane of biblical proportions. Occurring in 1991, this storm, named the Halloween Nor’easter, caused over $1 billion in damages and killed 12 people. It became a book which in turn became a movie.

The meteorologist Robert Case described this storm vividly:

[a] strong disturbance associated with a cold front moved along the U.S.-Canadian border on October 27 and passed through New England pretty much without incident. At the same time, a large high-pressure system was forecast to build over southeast Canada. When a low pressure system along the front moved into the Maritimes southeast of Nova Scotia, it began to intensify due to the cold dry air introduced from the north. These circumstances alone, could have created a strong storm, but then, like throwing gasoline on a fire, a dying Hurricane Grace delivered immeasurable tropical energy to create the perfect storm.

And who said weatherman aren’t sexy?

Storm, Storm, Everywhere A Storm

A “perfect storm” has come to mean any group of events which, by occurring at the same time, have a much great impact than if they had each occurred separately. Perfect storms happen all the time. For example, in politics:

IF there is a desire for change
AND IF the opposition is weak or divided
AND IF a potentially strong new leader arises,

THEN:
these conditions combine into a perfect storm to ensure a massive victory for one of the parties, and a thorough trouncing of the other.

Note that any one of these factors on its own would probably not be enough – it is the combination of these three that creates the storm.

Perfect storms also explode in the business world. The IPod is a perfect storm of good functional design, beautiful appearance and a slick marketing campaign. Even though there are many other players that are less expensive and perform nearly as well, the IPod dominates the media player industry because of the storm it creates.

A Storm of Information

In information development, a perfect storm is brewing that makes the Halloween Nor’easter hurricane look like a calm ocean breeze. And in this storm, the ayes have it, or, to be more precise, the I’s have it, all four of them.

The Bottom Line

The first I is Inefficiency. At all levels, companies are looking to cut costs wherever they can, and documentation is no exception. Creating well-formed, meaningful, accurate and up to date documentation is very expensive. Content management systems (CMSs) are also very expensive, but in the long run they lower costs and make the documentation process much more efficient. User guides that normally take months to publish can be assembled in weeks. It’s not unusual for these systems to pay for themselves within a few months. CMSs are so powerful, they are part of the other I’s, as you will see.

I Speak-ah Three Language - English Da Best

The second I is Internationalization. With technology, the world has shrunk to the size of a basketball. There is very little to stop companies from selling to markets throughout the world, especially if the product is non-physical, such as services or software. As a result, there is a need to translate documentation into various languages, but the cost is horrendous. CMSs alleviate some of this pain by allowing only the changed areas to be sent to the translator and by reusing content so that the same words don’t have to be translated more than once.

The Library Vs. the Net

The third I is the Internet. I certainly don’t need to explain the impact this has had on information. I can tell you that I feel very old when I speak to my 11-year daughter, as she researches a school project using the Internet:

“You know, back in my day, there was no Internet. If you wanted information, you had to drive to the library. Then you had to go through a series of dusty cards in large shelves, find the subject you wanted and then write down the Dewey Decimal numbers. If the librarian was there, and was not feeling too grouchy, she may have allowed you to interrupt her reading to ask for help. In a nasty voice, she would then tell you where to go. Then you had to stagger through a maze of book shelves, eventually finding the right aisle, slumber down the endless shelves of books, find the right shelf, bend down and strain your neck all over the place to find the book you wanted, only to discover….the book was out! It was a hard life, let me tell you...”


To which my daughter replied: “Come on dad, that was back in the 70’s. They didn’t even have cars back then..”

So much information (practical and otherwise) is on the Internet, it’s an incredibly obvious place to store all the documentation a user would need. The idea of creating PDFs and online help that ship with each release is absurd, because the instant these documents are published, they are out of date.

A more logical model is one in which all documentation is stored in a CMS that is continually published online. Whenever a user needs the latest and greatest version of a document, they go online and get it. With the right online tools, users can create their own custom output, tailored to their skill level, business requirements and the specific versions of the product they are using.

Hyperactively Interactive

The next I relates directly to the Internet – it is Interactivity. The days of one-way or limited communication are gone. However, it’s not enough for companies simply to provide a venue where customers can contact the head office. Companies have to provide an active area where people can freely post information and comment on their products. If they don’t, people have the will, and most importantly, the power, to do it themselves.

It’s quite amazing that on the websites of many stores, people rate and review the products offered, and that bad reviews appear everywhere. Such tolerance for unfiltered information would have been unthinkable a short time ago. Today, it’s demanded.

Now, imagine an online user guide where people can suggest changes and post comments. There is no better to terrify a writer into providing better content than that. The pain would be worth it, though, because you would end up with a guide that people can actually read, understand and use.

It's All About Me

These are the four I’s of the information development perfect storm. But these are actually all part of another I factor, one that is changing all business, and in fact, the world. This I is Individualism, and there are two parts to it.

The part is in the extreme niche marketing we see – products designed for groups within groups within still other groups. For example, clothing stores that try to appeal to everyone appeal to no one. Clothing stores that appeal to 18-25 female professionals may succeed, assuming this group is neither too general nor too specific.

The second part of Individualism is that people, as individuals, want to be heard as individuals and not ignored. This is part of the Interactivity factor discussed earlier.

Combine these two Individualism factors together into the information development field and what do you get? Documentation that:

• is custom-made for the end user (for example, an intermediate user who owns two of the companies other products, is using Windows XP, and wants the text to be displayed on screen in 12 point Arial on a cool grey background)

and

• the user can give direct feedback on, by directly contacting the company and by posting comments to specific topics online.

The New News
The new STC Toronto blog and website are small steps in acknowledging the perfect storm is coming, because they use a basic content management system that is:

• much less Inefficient that our previous system
• directly on the Internet, instead of using email and (gasp) mailed, printed copies as we did in the past
• Interactive – you can (and you should) contribute to it, and comment on any article.

The only factor left out is Internationalization, but that’s because English is the only language we use in our chapter. Who knows the future, though? If online translation tools improve, then anyone anywhere in the world could read our newsletter in their language. (I think the Swahali-speakers would particulary enjoy it.)

You Say You Want A Revolution
All of these I’s are creating the perfect storm for a revolution in how documentation is created. Any one of these factors on their own would probably not be enough. With two of these factors, the odds would be greater. But with all four factors occurring, it is an unstoppable force. All technical writers now face a choice – they can drown in this storm, or they can get out their surfboards and ride the waves of change.

Read More

Documenting the Referendum

Pity the poor Vote for MMP side in the October 10, 2007 referendum. (MMP is a form of proportional representation known as mixed-member proportional.) The MMP side never stood a chance for many reasons:

• most of the major newspapers were against MMP
• the referendum was held on the same day as the election
• very little was spent promoting the referendum
• the referendum campaign by elections Ontario was so neutral as to be meaningless
• the referendum was never a major election issue
• people were confused before and after the voting
• most people did not even bother to research the referendum

Regarding the voters and the ballot, it was reported that one scrutineer said: "They walk in and say, 'What do I do with this thing?' People don't get it. They want to get it. But they just don't get it."
The referendum was voted down by almost a 2-to-1 margin. Only 37% of people voted for it, which interestingly, is only 5% less than the 42% that voted to elect the Liberals and give them, even more interestingly, 66% of the seats.

Whether you are happy or angry with the results, though, is really irrelevant now. The question for information developers is: To what degree, if any, did the informational design, content and delivery of the referendum campaign and the ballot itself influence the result?

I reviewed the content of the official Elections Ontario referendum website. Although it presented the facts fairly well, I don't think it did a good enough job explaining the pros and cons of each system. Still, I think it contained enough information for people to at least try to make an informed decision.

The government sent a brochure to every voter, indicating a referendum was to be held, and ran regular ads in all the major newspapers. The ballot itself was quite clear: Do you want to keep the current system, or go with the one proposed by the citizens' assembly?

The information was out there, so why were so many voters confused?

I don't think the problem was as much with the information itself, as with the timing of the information, and indeed the referendum itself. An election is a complicated enough business as it is on its own - you throw in another, separate vote, and it's just going to get lost in the shuffle, no matter how well you try to explain it to people.

The principle actually reared its ugly head in the election itself - one issue came to dominate the campaign almost to the exclusion of all others - fully funding religious schools. Religion and politics are two extremely sensitive topics. Combine them together, and all other election issues fade away.
So, would the result have been different if the referendum had been held separately from the election? Possibly - at the very least, I think there would have been more awareness. In the final analysis, though, people would still have to make an effort to learn what's being proposed.

The lessons for information developers are clear:

• Too much information can be as bad as no information.
• A document is only as valuable as the willingness of its reader to use it.

Now if only they had had professional information architects designing the infamous butterfly ballot...

Read More

Technical Writing and the Art of Haiku

Japan is an unceasingly astonishing nation. Only a few short decades after being bombed into the stone age during the second world war, Japan rose from its ashes and not only survived, but thrived. The very best electronics are made in Japan. The Japanese car industry has demolished the North American "Big Three". While Ford, GM and Chrysler drown in debt, Toyota, Honda and Nissan are debt-free and have continually growing sales.

Part of the secret of Japan's astounding success is the ability of its people to work effectively in teams. There is less emphasis on individuality, and more on the group as a whole. That is why factory managers, for example, often wear the same uniform as their workers and have their offices directly on the factory floor.

GroupThink
This team mentality pervades all aspects of Japanese society. If you are sick, you wear a surgical mask for the public good. When you work, it is always as part of a group; you are strongly encouraged not to upset the group dynamic with radical ideas. Even government, industry and the educational system all work closely together in an effective three-way partnership to continually produce and train the required workers.

This "group think" has created enormous wealth for Japan. However, it has come at a price of a different sort - a lack of creativity and free-thinking, both critical in creating new ideas. The Japanese excel at improving greatly on existing technologies. They are less skilled at creating new technologies. That is why very few Nobel prizes have been awarded to Japanese citizens.

Creative Creativity
Japan has been making an effort to change, to break out of its powerful group mentality and thereby become more creative. Some corporations employ scientists to conduct pure research that may not lead to anything of value.

Research for its own sake is a difficult concept in Japan. The Japanese are, above all, a practical and pragmatic people. Therefore, for them to allow experimental work like this is quite incredible. Unfortunately, there no scientific way to guarantee the generation of effective and practical new technologies. The only method is to find creative people, put them in a lab, throw lots of money at them and hope that something develops.

Of course, creativity applies to so much more than the business world. It applies to the arts, too. In fact, although you may be able to survive in business without being too creative, you would not survive as an artist, where creativity is essential. Even in the arts, though, Japan has created a formal structure and process, and the best example of this is Haiku.

Poetry in Motion

Haiku is a structured form of poetry that is over four hundred years old. The poems are three lines long. The first and third lines typically have five syllables, and the second line has seven syllables.

Here is a modern example:

Worker bees can leave
Even drones can fly away
The queen is their slave

The challenge is to be creative within these rules. Because this can be quite difficult, there are many Haiku poems that do not follow this structure, yet still could be considered art.

With this in mind, I present to you a series of Haiku-style poems that I confess do not follow the formal structure. In fact, every technical writer must face the choice of following an existing structure in their work (a style guide), or going outside of that structure when necessary. That is your choice - make it a good one.

And now, on to the poetry...

The draft returns
On its cover, two words
"Needs work"
The horror, the horror

Auto-numbering in Word
Ah, the sheer joy
It's as easy as
13, 7, 42

"Let's take it offline"
the manager sings
We are offline. We are online.
What are we - the Borg?

The marketer says:
"architect our software"
"leverage our knowledge"
"empower our synergy"
Marketers...
Such funny creatures

Young Jedi tech writer
His mind corrupted with unstructured Frame
and the madness of Word
You must unlearn
all you have learned

XML is simple
Just elements, attributes & variables
Have no fear
It's not rocket surgery

FrameMaker conditions - solid as concrete
FrameMaker variables - beyond unbreakable
FrameMaker text insets -
I weep uncontrollably

The programmer writes:
"using the zeta function
the new class may
inherit the variable
or be destroyed"
What colour is the sky
in the programmer's world?

The PDF file size - so very large!
The business analyst asks:
"Can't we just use
a smaller font?"
Must control
fist of death

I see the demo
of the shiny new CMS
XML, multiple outputs, versioning, workflow
Let the drooling begin

The cover
of the shipped guide torments me
"User Mnaul"
Quick and painless
It is an honourable death

XML, CSS, CMS
HTML, XHTML, XSL-FO
PDF, TIFF, GIF
Alphabet soup
Makes me nauseous

The 2,000 page document is complete
Peace at last
What - more changes?
I insert the CD ROM
delicately into
the reviewer's skull
The nervous tech writing students
Await my interview of them
Entering as the Emperor, I bellow
"Bring me that one -
He amuses me."

A guide is required
27 versions
6 different formats
14 languages
Excuse me while I place
gingerly into the paper cutter
my aching head

Testing the software
The message appears
I chuckle heartily
"Error, big"

Savouring the smell
of the freshly printed manual
in the morning
It smells like
printer toner

343 screenshots
All to be redone
Years later, from the tech writing department
You can still hear the screams
See the SME
who does not return his draft
See Igor, the seven foot tech writer
Run, SME, run!

The haughty reviewer
Demands to see the document
I send an XML file
He has no viewer
Vengeance is mine

Adopted by the Adobe tribe
I receive my First Nations name
Know it well
"Dances with Fonts"

Read More

The Da Vinci XML Code

As information developers whose job it is to seek and document the truth, we should always be skeptical when a novel claims to be based on the truth. Yet such is the central claim of Dan Brown's best seller, The Da Vinci Code. In this novel, members of a secret society (the Priory of Sion) are portrayed as the protectors of Jesus' bloodline. In the book's preface, titled Facts, Brown states that the Priory of Sion is an actual society. This claim is based on the discovery in 1975 of parchments in the French National Library claiming to list members of this society, including such notables as Isaac Newton, Botticelli and Leonardo da Vinci.

In reality, however, the Priory of Sion was the invention of an eccentric Frenchman, Pierre Plantard, who was obsessed with creating a reunified Europe ruled by the Catholic Church and a divine monarchy. He imagined himself as the leader of this empire, fabricated the documents, and placed them in the national archives. In the early 1990s, Plantard confessed to his deception, yet Dan Brown still claims the Priory of Sion is a real and ancient society


There are many other distortions and historical inaccuracies littered throughout this novel. So why is The Da Vinci Code a best seller? Because people love a conspiracy and don't allow details like the truth to get in the way.

The Theory Behind Conspiracy Theories
Conspiracy theories and theorists abound. Some theorists claim that the government has covered up evidence of contact with aliens from other worlds. I remember seeing a film of a supposed "alien autopsy", which was later exposed as fiction. Other theorists believe that the earth is flat and therefore the entire NASA space program is an elaborate hoax. You have to wonder if these believers would include their membership in the Flat Earth Society on their resume.

Many conspiracy theories emerged soon after the September 11, 2001 attacks. Despite the overwhelming evidence that the attacks were carried out by foreign terrorists, many people believe that the Twin Towers were brought down by a "controlled explosion", that a missile (not a plane) slammed into the Pentagon, and that the U.S. government launched the attacks as an excuse to wage war.

Conspiring the Theorists

I think the proper way to deal with conspiracy theorists is to create conspiracy theories about them. Did you know all conspiracy theorists are members of a secret society called the Conspiratori, that they came from another planet and control the banks, economy, military, and entertainment industry, and that they are responsible for all wars, pollution, and the fact you can never match up your socks after washing them? Can they prove they are not members of such a society?

The problem with conspiracy theorists is not that they are wrong, but that they distract us from uncovering what's really going on in the world. The truth is not a "conspiracy" at all (although it may take some effort to reveal), and is often more unbelievable than any conspiracy.

A Religious Experience
Returning to the topic of religion, archaeologists, biblical scholars and religious historians have made exciting, actual discoveries, which are causing some people to reexamine their religious views. The most recent of these is the discovery of ossuaries that allegedly contain the remains of Jesus and his "family". These discoveries are not intended as attacks on religion, but represent a fresh look at some of the world's oldest cultures.

Now, you would think that something as mundane by comparison as information development would have no place for conspiracy theories. But as surely as Leonardo painted the Mona Lisa, you'd be wrong. In fact, there is a real conspiracy so deep, so large and so wide, it is extraordinary how little it is discussed.

The Real Conspiracy
This conspiracy costs the world billions of dollars and millions of lives a year, and causes widespread poverty, hardship, and misery. When it's revealed to them, most would agree such a conspiracy exists, but would say there's very little they can do about it. Many corporations and governments may know of this conspiracy but don't want to commit the time, effort and money to resolve it.

What is this conspiracy? It is the conspiracy of information unavailability and information chaos. Much of the information that people desperately need either doesn't exist, or is so chaotically organized it may as well not exist. Most organizations do not have information management systems, and are therefore endlessly duplicating their content, creating chaos. Most organizations have no formal system to get feedback from their users on what is missing and what can be improved. Most content is not structured using the newer technologies, such as XML, which is fast becoming the standard to organize and classify information.

The Hidden Truth
To be sure, this conspiracy is different from typical conspiracies, in that there has been no direct effort to hide it. However, it is still a conspiracy of sorts, because there has also been no major effort to reveal it and its tremendous effects on our world. It is a conspiracy of indifference, laziness and apathy.

Because of this conspiracy, most information developers struggle endlessly. They expend huge amounts of energy and time fighting the inefficiencies inherent in their tools and processes.

An Ideal Conspiracy
It does not have to be this way. The ideal information management system would:

• store each piece of information once and only once, including everything from company and product names, to procedure steps, all the way up to overviews and descriptions
• maintain the information in a pure XML format, forever separating the content of the information from its form and appearance
• indicate to authors and reviewers the documents in which each piece of information is reused
• automatically notify reviewers when the information they are responsible for changes
• allow reviewers to create online discussions debating the changes until a resolution is achieved
• automatically retain an unlimited number of versions of the information, allowing writers to revert back to any version
• allow writers to classify information as intended only for specific versions, and mix and match the various pieces of information as required for each version
• automatically indicate which information has changed
• automate the process of creating and updating indices
• allow writers to easily design WYSIWYG templates for all outputs, such as print, help, PDAs and the Web, and centralize the storage of these templates
• be implemented throughout an entire organization, not just in the tech writing department

And most importantly, the ideal information management system would allow outside readers to give direct feedback to the information developers.

Of course, systems with most of these characteristics exist, but they are very expensive and difficult to implement. However, they often pay for themselves in a relatively short time.

A Document is a Terrible Thing To Waste
The ramifications of companies not using information management systems extend far beyond technical writing departments. Companies waste millions maintaining the information they have and lose millions more in lost opportunities. Specifically:

• Millions are wasted on technical support because users could not find the information they need, forcing them to phone in.
• Millions are wasted because users don't know how to efficiently or properly use the products and services they've purchased, and unknowingly take "long cuts" instead of shortcuts.
• Millions are wasted because users return products that function properly, but which they could not figure out how to use.
• Millions are wasted in lawsuits. One medical company lost a lawsuit because they did not supply critical information in a consistent manner.

Imagine There's Nothing Hidden, It's Easy if you Try
When information is not shared, the world loses. Imagine if all publicly known medical information could be shared on a single database accessible anywhere in the world. Actually, the truth is not far off - many doctors confess they sometimes now Google their patients' symptoms. Sites like Google and Wikipedia are useful, but they are not formal, official databases of information. An authorized Medical Wikipedia that could be accessed by anyone could save countless lives.

Imagine the progress that could be made if more organizations would store their information efficiently and be willing to share more of it. One gold mining company actually did this. They allowed anyone who wanted to to submit ideas on how to locate areas that could potential contain gold. A wide variety of people responded. All the information was shared. The result? Millions of ounces of gold was found, and the company exploded in value.

This is the true conspiracy theory: the conspiracy of information. Expose the conspiracy. Forget the Da Vinci Code – crack the XML Code and get the truth out.

Read More

The Documentation Deficit

There is something that has no mass, yet carries a crushing weight. It is colourless, odourless and tasteless, yet affects many lives every day. It has no form or shape, yet can be more powerful than any army and just as lethal. It is everywhere yet cannot be seen. It exists between individuals, between countries, and everything in between. Without effort, it quickly grows. It is easy to get into but difficult to get out of. The rich lack it and the poor have much of it. With the right amount of it, life can be enjoyable, but with too much of it, life is a misery.

What is this strange substance? It is debt, and Canada, and Canadians, are drowning in it.

Buddy, Can You Spare a Trillion?
The Canadian federal government's total debt is currently over $480 billion, costing $93 million in interest payments every day. But this debt is only part of the picture. The combined federal, provincial and municipal debts total $800 billion, or just over $26,600 per Canadian.

But wait, there's more! In addition to government debt, Canadians have their own, individual debts, called personal debt. As of the end of 2004, total personal debt in Canada was at a record level of $752 billion, not much less than the total government debt. With relatively low interest rates, it's easy to see why Canadians are racking up huge debts in the form of mortgages, credits cards, bank loans and lines of credit. It's amazing to read about families earning six-figure salaries and yet being unable to make ends meet because their expenses exceed their income. (Gotta have the BMW, the private schools for the kids, the cottage and, of course, trips to the Bahamas!)

Now, when you add the government debt of $800 billion to the personal debt of $752 billion, you get a whopping $1.55 trillion dollars of total debt. That's 1.55 million million dollars.

Big Numbers, Bigger Problems
It's almost impossible to imagine how large 1.55 trillion is. A rope 1.55 trillion centimeters long would circle the Earth 387 times. (It would also be cut into pieces fairly quickly because everyone needs rope now and then.) If you had $1.55 trillion dollars, you could give each person on Earth $236 dollars. (Think of all the rope that could buy). Finally, 1.55 trillion seconds is almost 50,000 years, which is about how long it would take to make all that rope. It is truly a huge number. If it's any consolation, the United States federal government alone is over $8 ½ trillion in debt. (U.S. dollars, of course.)

At this point, we haven't even discussed corporate debt, nor the debts of other countries throughout the world. If you were to add up all the government, personal, and corporate debt for the entire planet, you would obtain a number approaching infinity. It's a miracle God hasn't repossessed our planet.

Daffy Debt Definitions
Debt is such a monster that we actually need two words to describe it:

• deficit: the amount of debt accumulated in a specific time period, usually a year
• debt: the total of all deficits

To further depress you, financial debt is really only one kind of debt. In fact, debt (or deficit) can be applied to others areas, for example:

• If you consume more calories than you expend, or if you never exercise, then you have a health deficit.
• If you do not continually update your work skills, then you have a career deficit.
• If you do not get enough sleep, then you have a sleep deficit.
• If you only focus on the physical, and never explore the meta-physical, then you have a spiritual deficit.

Dealing with Debt
All these areas share common principles and characteristics. To achieve something worthwhile, work and effort are required. If you do not make the effort, the debt begins and grows until it can be impossible to fix, resulting in a state of bankruptcy. Conversely, if you make a continuous effort, the debt can shrink and be held to a manageable level or eliminated altogether.

Tragically, many people don't realize they have a debt until it becomes critical. Some of them max out their credit cards and borrow money just to make the interest payments. Others eat junk food, drink, smoke, never exercise and then have a heart attack. Still others work at one place for many years, never update their skills or network with others, and then, to their complete shock, are laid off and are so traumatized they find it impossible to look for work. All of these are examples of debts left unchecked. And so it is with documentation.

The Documentation Deficit
The "documentation deficit" formula is simple:

[work hours required to update documentation to a proper level]
minus
[work hours actually expended updating the documentation]
equals:
the documentation deficit or surplus

Although it has never been formally measured, the documentation deficit in many companies is enormous. Many establishments have tens or even hundreds of thousands of printed or electronic pages of information throughout their manuals, their websites and their internal documentation. When was the last time it was all properly reviewed and updated? Things change constantly, especially in software. The energy required to keep the information relevant, correct and complete is often so great that many companies don't even bother trying. They triage, they prioritize and fix the more obvious or public areas. The result? Documentation that is in one of the "in" states - incomplete, inaccurate or simply insane.

Paying Your Debt to Society
The good news is that a few companies have begun to realize they have a problem. Just as the federal government is now expected not to run deficits and pay down their debt, corporations are slowly beginning to realize the extent of their documentation deficits and are making the necessary payments.

They are hiring information developers and information managers. They are upgrading their documentation tools and implementing content management systems. Yes, there is much more that can and should be done. But it's a start. And perhaps one day, companies will announce that they have eliminated their documentation deficit as proudly as they would their financial deficit.

Read More