The IT Guy Says: Back it up!

Doctors constantly tell us to eat right, exercise regularly, and avoid smoking. Yet there are many doctors who are smoke, are fat, or are fat smokers. Hence the term, "doctors make the worst patients".

We who work in information technology (IT) are no different. A doctor implores people to live healthily; IT professionals implore people to back up their data. Yet there are many IT degree professionals who fail to do this, thinking that hard drive failures and accidental file deletions don't apply to them.

Technical communicators commit two sins in this area. Many of us don't back up our files, or if we do, we don't communicate to others how to do this. I am guilty of these crimes, and sentence myself to writing this article explaining my own multi-faceted approach to file storage and backup:

Back Up Your Files Already!

I have a three-stage approach to file back up and storage. At a minimum, you should do stage 1, but consider the other stages also.

Stage 1: Buy an external hard drive
Buy an external USB hard drive, attach it to your computer, and back up your files every day. Now, if you don't have too many files, you could use a memory stick, but its performance can be quite slow compared to the hard drive. Besides, who amongst us really has only a few GB of data?

External hard drives come with their own backup software, or you can use a third-party program, many of which are free. I like Microsoft's SyncToy, which you can set up to synchronize files on your computer to your backup drive.

I recommend setting up your backup software so that it only contributes files to your backup drive, and does not delete them. Although you'll end up with extra files on your backup drive, it's better to have them and not need them than to need them and not have them.

Stage 2: Use an online back up service
While at a minimum you should back up your files to an external hard drive, this practice has one major limitation. If your computer and backup drive are stolen or destroyed, you are out of luck. One inexpensive way around this is to back up your files onto a CD or DVD and then store this in another location. The problem, of course, is that your file collection keeps changing.

An online backup system backs up all your current files to a secure location on the Internet. Even if your house burns down, your files are still available.

There's many online services to choose from: I use iDrive which had the best pricing: 5GB for free, or 150 GB for $50/year, about $4 per month. You can configure it to automatically back up files as they change, thus ensuring that your backup always reflects your current file list. In addition, you can access your backed up files from any computer with Internet access.

Stage 3: Move to the cloud
All of my non-financial information lives on the cloud (the Web). This includes Google Docs for documents and spreadsheets, Gmail for email, Google Calendar, an iGoogle "to do" list, and this blog.

The beauty of having as much of your data on the cloud as possible is that you can log into any computer and access your data. When you combine cloud storage with an online backup service, you have full access to your digital world anywhere, anytime.

The downside is that security becomes an issue. That's why it's important you don't store any sensitive information online, such as financial or banking information. The balance between security and convenience did not begin with the Internet, nor does it end with it. For example, credit cards offer convenience, but also the potential for fraud. As with all things, you need to use your best judgment.

***

This is my three-stage approach to backup. Feel free to describe your approach by commenting on this article.

Read More

Ultimate Doc Tease

The Ultimate Dog Tease YouTube video has been viewed 30 million times. It's a hilarious clip of an unseen owner unbearably teasing his dog about food. If you haven't seen it yet, watch it now, then return to this article.

***

Pretty funny, eh? Andre Grantham, the creator of this video and several other talking animal videos, is from Halifax, Nova Scotia. He was unemployed when this video was released, but soon received a job offer.

What makes this video so funny is its simplicity. There are no special CGI talking animal effects - the movement of the dog's mouth is all natural, as is the dog's ever hopeful expression.

Because we don't see the owner talking, and because the "talking" done by the dog doesn't match the dog's mouth exactly, it would be quite easy to dub in your own script. I'm not a video editor, but here's the script I would write for this video:

Me: So I got this draft back.
Dog: Yeah.
Me: Yup - a SME took the time to review it, can you believe it?
Dog: Yeah.
Me: Anyway, I looked through the whole draft...
Dog: Looked through the draft, yeah.
Me: And the reviewer wrote on it..
Dog: Yeah.
Me: NEEDS WORK!
Dog: Ohhhhwwww.....you're kiddin' me.

Me: Then I started working on this other guide.
Dog: Yeah. 
Me: A user guide. 
Dog: A user guide, yeah. 
Me: It had lots of really nice screenshots. Very pretty.
Dog: Yeah. 
Me: We were all set to release the guide, but then you know what? 
Dog: What?
Me: The marketers changed the screen design!
Dog: Ohhhhwwww.....

Me: Then my boss called me into his office. 
Dog: Yeah.
Me: He said we'd be getting a brand new content management system.
Dog: What would be in it?
Me: Well, it would have versioning, multiple outputs, workflow management..
Dog: Workflow management, yeah.
Me: ...be DITA-based and fully customizable.
Dog: Yeah.
Me: My boss said we could get it real soon.
Dog: Yeah.
Me: But to pay for it...
Dog: Yeah.
Me: ...he'd have to lay off me and half the writers!
Dog: Ohhhhwwww.....

Read More

A Life or Death User Guide

The state of Oregon will soon ban the sale of suicide kits in response to the tragic death of 29 year old Nick Klonoski, a depressed man who killed himself using a kit he ordered through the mail.

These kits cost $60 and contain a plastic bag that fits over the head, a plastic tube for attaching to a tank of helium gas, and detailed instructions.

Although Oregon allows doctors to help terminally ill patients end their lives, it certainly has not legalized suicide for mentally ill individuals. The fact that anyone can easily purchase these kits has spurred the government into action.

This very sad case raises a disturbing thought experiment for information developers:

Imagine you were forced, under threat of death, to develop the user guide for this suicide kit. You are given all the technical specifications and procedural information, but you have permission to write any text you wish. You know that some of the users are not terminally ill, but are instead depressed.

What information would you include in your guide, which is literally a "life and death" document?

Knowing our users, we would include a warning such as:

WARNING! This kit is only intended for people who are terminally ill. If you do not have a physical illness, or think you might be depressed or suicidal, please call 911 or the local suicide prevention number....

Now imagine the same scenario, but this time the manufacturer of the kit must approve your draft. They have told you that you cannot include any type of warning for depressed people. If you do, it will be deleted.

Now what do you write? How do you give a user information without explicitly stating it? Simple - by implicitly stating it, as follows: 

Note: This kit is only intended for patients that have been diagnosed by a doctor as having a painful and terminal illness.

The irony here is that this note could be more effective than the traditional warning. It does not explicitly tell a depressed user what to do. Instead, it subtly suggests that this guide does not apply to them. It plants a seed that could save the user's life.

Returning to the real world of ordinary documentation, we often have to balance what a user wants to know against:

• what a user needs to know (even if they don't want to know it)
• the requirements of the manufacturer

This nightmare scenario of the suicide kit guide illustrates how difficult it can be to balance these competing needs and wants.

Now, most users ignore documentation, and certainly most depressed people would ignore both the warning and the note. But not all of them will, and if the inclusion of this paragraph saves only one life, it will be worth it.

As the Talmud, the ancient book of Jewish law, states:

"Whoever saves a single life, it is as if he saved an entire universe."

Read More

Lessons from the 2011 Canadian Election

The results of Canada's recent federal election were truly stunning. If you're not Canadian (or are but have been living under a rock), here are the results:

• the Conservatives won a majority of the districts (or seats), capturing 167, up from 143
• for the first time ever, the NDP formed the official opposition by winning 102 seats, up from 37
• the Liberal party was reduced to third place, winning only 34 seats, down from 77
• the separatist Bloc party in Quebec was reduced to "junk bond" status, down from 49 seats to only 4, out of 75 seats in that province

What can technical communicators learn from all this?

Let the learning begin...

Lesson #1: Stability and change can co-exist

The election results were paradoxical to say the least. Only 40% of Canadians voted for the ruling Conservative party. However, voters also left the Liberal party in droves, elected more NDP MPs than ever, and dumped the ruling Bloc party in Quebec.

Did voters vote for change or for more of the same? They did both. Due to the peculiar nature of our first-past-the-post voting system, the Conservatives gained only 2% in the popular vote, but 17% more seats, more than enough to obtain a majority. At the same time, the NDP gained 13% in the popular vote, but increased their seat count a staggering 175%. The numbers don't lie, but they sure tell a funny story.

Existing documentation projects, as well as software, share a similar paradoxical quality. They must be stable enough so that current users can continue to use them without getting lost or confused. At the same time, documentation is constantly evolving as the product changes and the documents are updated.

Striking the right balance between stability and change is one of the great challenges of our profession. That's why is often liberating to work on new projects, but even then, they often need to be developed within existing standards. 

Lesson #2: Sometimes less is more

NDP leader Jack Layton gained more seats and is now the official opposition party. It may seem the NDP gained more power, but strangely, they may have even less. This is because previously the NDP was one of three parties that held the balance of power. The NDP could and did threaten to join with the other parties to bring down the government. Under the current Conservative majority government, the NDP have lost that power. That is, they won, but they also lost, showing that less is sometimes more.

"Less is more" is one of the axioms of our profession. Shorter, concise paragraphs and topics are much more powerful and effective than longer ones. In other words, "when in doubt, leave it out."

Lesson #3: Hubris is death

As described previously, the leaders of the Liberal and Bloc parties joined forces with the NDP to bring down the government and force an election. Bloc leader Gilles Duceppe believed he would continue his winning streak in Quebec. Liberal leader Michael Ignatieff hoped to become the next Prime Minister, or, at the very least, increase his party's seat count. Each of them conveniently provided the noose around which to hang their own neck.

Not only were the seat counts drastically reduced for these two parties, both leaders lost in their own riding. They had no choice but to resign, leaving each of their parties in tatters.

If there's one thing the public cannot tolerate, it is the politician who gives even the slightest impression that they are "owed" a victory. Arrogance, hubris, and a sense of entitlement are all a death sentence in politics.

Political campaigns are one long job interview, where each leader tries to convince you to "hire" them through your vote. Hubris is the last quality you want to exhibit in an interview. You need to strike the right balance between confidence and humility. You want to show that you know your stuff, but are not a "know it all".

In addition, technical communicators are often called on to be user advocates. We push for simplicity, clarity, and consistency, not just in our documentation but in the products and services we document. However, we must realize we do not own these products: the product managers and others who work directly with the end user do. We can advise, but we cannot dictate, for that is the essence of hubris.

Lesson #4: "Top" and "bottom" are interchangeable

The Conservatives are now on top; the Liberals on the bottom. This is not a permanent arrangement. Unless you are living in a one-party state, the ruling party never stays in power indefinitely. As high as the winning party is now is exactly how high the losing party will eventually be. Top and bottom are but temporary states.

Now, if you have made the transition from a traditional, book-based authoring environment to a topic-based one, this principle becomes apparent. Instead of creating pages, chapters and books, you create individual topics that can stand on their own. You assemble and organize these topics into logical groups, such as the TOC folders within an online help system. You can easily move these topics around, quickly relocating them from the top of a document to the bottom, or anywhere else. Again, top and bottom are but temporary states. 

Lesson #5: Take your time

The Liberals now have about four years to rebuild their party. They should use the time wisely, and not rush, otherwise they will never recover. A "sub-lesson" to this lesson is that those who do not remember the mistakes of the past are condemned to repeat it.

For any document or documentation process, especially if it is new, take your time. It's a cliché to say, but most people don't plan to fail - they fail to plan. More documentation projects fail or are much more difficult than they need to be because no-one took the time to stop and carefully analyze the requirements and implementation process. They just dove right and started developing content, without first deciding how the content would be used or identifying who would actually be reading it.

I often hear the refrain "we don't have time to do that". I would counter that you don't have time not to. The Liberals have all the time in the world - do you envy them? 

Lesson #6: Branding is everything

The final and most important lesson from the election is the importance of branding.

A brand is the idea or image of a product or service that people can connect with. Branding is the communication of this idea (through marketing) so that it is perceived as being uniquely recognizable from other products or services.

When we think of brands, we typically think of large companies such as Coca Cola, Microsoft, Dell, IBM, and Toyota. However, brands can be applied to anything - even you. (We'll get to that in a minute.)

Political parties know the importance of branding. To put it mildly, the Liberal brand has been suffering for the last few years. Their continued drop in popularity and seat count was inevitable, no matter who was leading the party. The Bloc's brand was associated with sovereignty - a concept that most Quebeckers seem to have rejected for now with their embrace of the federalist NDP.

The NDP's branding, especially in Quebec, was simple and brilliant. One of their Quebec TV ads had dogs barking at each other, with the tag line: "Always the same debates that lead nowhere", followed by "It's time for a change. Work together." This branding was so powerful it catapulted the NDP from one seat in Quebec to 58. Some of the new MPs were university students, including a nineteen year-old voting for the first time in his life. Another student did not even live in the riding she was running for, and was on vacation for part of the campaign. It did not matter; such is the power of branding.

Think that branding doesn't apply to you? Think again. When you have a job interview, and even after you've been hired, you are a brand. You must demonstrate and transmit the key qualities that define you as a technical communicator, and a person. These could include: outstanding communication skills, efficiency, patience, knowledge, technical expertise, a team player, and above all, an improver. In an interview, you must clearly show in your work experience that you are passionate about your profession and have actively enhanced the quality of the documentation and the documentation process. That is your brand - your brand is you.

These are the lessons from the election. There are many others. Anyone who wants to discover these has my vote.

Read More

A no-good lying email

Imagine my excitement when I received the following email after subscribing to a magazine:

The latest edition of your magazine is now available. Print subscribers: your issue has just been put in the mail. Please watch for it in your mail box in the coming days.

Woo hoo! I would soon be receiving my first printed issue of the magazine. Oh boy, I could hardly wait.

But I did wait. And waited, and waited, and waited some more.

Finally, after waiting about a month, I called customer service. The service rep checked his computer-database thingy, and proclaimed that due to the way new subscriptions are processed, my first edition would not be arriving for another week.

In the words - the email I received was a bald-faced lie. I suggested to him that, er, maybe he should look into this, because it's "rather disconcerting" to receive an email stating something which is, in fact, not true.

Which was a polite way of saying that the magazine had done a piss-poor job integrating their mailing and emailing systems.

This is a common problem. It happens because there are two types of information in this world:

• Type A: officially distributed information
• Type B: the true version of Type A

Because most of the people running organizations are not technical communicators, they have no problem mixing up these types. They will cheerfully send out information they know is incorrect, with the mantra that "hey, nobody reads these things anyway, so what's the point in trying to get it right?"

As technical communicators, this should make our blood boil, if not explode. Creating, sending or distributing inaccurate or false information is a crime against humanity. Unfortunately, we are the only judges and prosecutors for these transgressions. We're also ultimately the only ones who care enough to make it right and have the skills to do so.

But for now, I'm dropping the charges.

Read More

Name that document

I saw a document on the news today with two entries, each followed by a number.

It's not a TOC.

It's not an index, either.

It was a hand-made sign summarizing yesterday's historic event: the irreversible deletion of one (1) Mr. Bin Laden:

OBAMA: 1
OSAMA: 0

I couldn't have documented it better myself.

Read More