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