Un-super Size Me

It's astounding that the very people whose job it is to be concise fail to be concise on their most important document: their resume. I plead guilty to this word-crime.

After consulting with an expert, I reduced my resume from 650 words to 300. How? By hacking off the crap that had accumulated over the years, and then simplifying the leftovers.

My resume is now a page and a half and can be read in 20 seconds. Considering the mountains of lengthy resumes employers must sift through, a short and concise one is a breath of fresh air.

Isn't this extreme editing? Yes, it is. Try it; you can always back up your super-sized resume.

Read More

Introducing the New & Improved Citizens Guide!

The Canadian government recently updated their guide for new Canadian citizens: Discover Canada: The Rights and Responsibilities of Citizenship. Apparently, the last release had a few omissions. In the current version, there's more information on Canada's history, and a greater discussion on our nebulous "Canadian values".

As an former immigrant myself (my family came over from England in the 1970s), I appreciate the handy new information in this guide. Apparently, it's important to have a job, and the guide even makes a suggestion for this. It says joining the army is: "a noble way to contribute to Canada and an excellent career choice." I guess I should quit my career as a tech writer and sign up. Or perhaps I could be a covert Military Tech Writer. I can picture me stationed in Baghdad, with the sergeant barking out the order: "Dammit, Brooke. I need that quick start guide and I need it now!"

The guide also lets new citizens know that "barbaric cultural practices that tolerate spousal abuse, honour killings, female genital mutilation or other gender-based violence" are forbidden. I'm sure that information will come in handy. Picture this discussion:

Crazy father: I'm sorry, daughter. I saw you with that boy whom I'm forbid you to be with. I'm afraid you must be sacrificed for the family honour.

Innocent Daughter: Sorry - you can't. It's specifically forbidden on page 32 of The Guide.

Crazy father: Oops! You're right. I must have missed that section. Was it in the TOC?

Let's analyze the potential users of this guide. The vast majority of immigrants who come here do so precisely because they want to escape the horrors of their former countries and live in a peaceful, secular, democratic state. They know these types of acts are illegal here. The tiny minority that think they can commit these crimes are not going to be swayed by a manual.

It takes much more than a guide to make someone a successful citizen. As with all documentation, guides may help, but, in the end, the user must choose to learn.

Read More

Remembering The Wall

Twenty years ago, the wall came a-tumblin' down in Berlin. Bewildered East Berliners flowed into the west, marvelled at the material delights, then returned to their drab homes. About a year later, in the greatest act of single-sourcing in history, East and West Germany were merged into a single entity.

I was lucky enough to have seen the wall only three years earlier, in 1986. Berlin was one of the many stops of my grand tour of Europe: 22 countries in 60 days. I remember scrambling to the top of an observational platform near the wall. I, along with about 20 other insane college students, crammed together at the top, where we could easily see over to the other side. We saw the wall on our side, a "no-man's land" strip about 300 feet wide, and finally the wall on the East German side, where East German soldiers laughed at our packed-together motley crew.

If you had told me that three years later these walls would be gone, I would have said: "Yeah, right. And someday all the world's computers will be magically connected, everyone will have their own portable phone, and you'll be able to buy TVs 3" thick and 52" in diameter. Like that's ever gonna happen..."

Many people don't realize the two walls ran not only through a city but through the entire country. I wonder what happened to all the concrete? It would have been tough to recycle it.

Off the Wall

We must be thankful to live a country that has no walls to imprison its people. (Except for the ones in jail, of course.) However, there all walls of other sorts. The walls that wreak havoc in our profession are the ones blocking the free flow of information. Companies build virtual walls (or silos) around their various departments, resulting in misinformation, disinformation, inconsistent information, little information or no information being circulated amongst the employees.

In software companies, a business unit for a specific product can be comprised of developers, QA testers, marketers, salespeople, trainers, technical writers and product managers. How often do these people communicate with each other and share information? If they're not communicating, they are building - building the wall.

So I say to these workers, and to the company presidents, vice-presidents, CEOs, and managers at all levels:

Tear down these walls!

Read More

How Long is a Piece of String Theory?

"If you need to get some string, get this string. It's the greatest string in the world. It's almost rope."

You can't get more deadpan than the brilliant observational comedian Steven Wright, who is imagining the ultimate ad to sell strings. Strings are as commonplace as cellphones these days. In addition to the plain old strings Wright describes, you can have:

• stringed instruments
• pearls on a string
• a string of islands
• drawstrings
• a string of ideas
• string beans

You can pull strings, be strung out, string a person along, be second string, string lights, and keep someone on a string. When it comes to describing this particular object, there's simply no strings attached.

The Mother of All Stings

Leave it to theoretical physicists to make something as simple as a string the foundation of one of the most complex and fascinating scientific theories ever imagined: string theory.

String theory proposes that everything in the universe is made up of tiny, vibrating strings of energy. The way the strings vibrate determines the type of particle formed. In this theory, strings make up quarks, which in turn comprise electrons, protons and neutrons, which make up atoms and finally molecules.

If string theory could ever be proven, it would literally be the answer to the universe. That's because string theory is a unified theory, a theory that unites the study of the very, very small (quantum mechanics) with the very, very large (general relativity). It would explain how all matter behaves, from the components of atoms, all the way up to planets and galaxies. That's why a unified theory is also called a theory of everything.

My, What Small Strings You Have

The problem is that it may be impossible to prove string theory. The strings would have to be unimaginably small: a string would be to a hydrogen atom what a small tree is to the solar system. If strings exist, their tiny size would make them unable to be detected directly. Also, for the math in string theory to work, the strings have to exist in eleven dimensions. (I have enough trouble with multiple text conditions.)

What's really fascinating, though, is the idea that by determining the basic building blocks of the universe, we can solve the mystery of the universe. Now, if we could identify the basic buildings blocks of technical communication, it could be a unified theory for our profession.

I Object

Initially, it would be tempting to identify the basic tech comm objects as the actual language or visual constructs used when communicating, for example:

• letters, numbers and symbols or
• words and pictures or
• nouns, verbs and objects or
• overviews and tasks

While it's true these elements are all used to assemble documentation, realizing this doesn't bring us any closer to exactly what technical communication is or does. In fact, taking things to their logical conclusion, all communication is made up of ink or pixels, but this doesn't explain anything.

We need to ask: what is the true purpose of technical communication, and what does it actually mean to achieve this purpose?

Tech Writing On Purpose

The purpose of technical communication is to give users the information they need to understand concepts and complete tasks. That is, all technical communication is made up of two basic components:

• conceptual explanations or overviews
• procedural explanations or procedures

These are the two types of technical communication to be unified, just as string theory attempts to unify the small and large. We need to identify the common elements in each type, and then see if they can be synergized.

Let's start with overviews. To have a user understand a concept, we need to explain that concept to them, and wherever possible, show a real-world example. (An example would be appropriate here.) For example, to explain what character formatting is, you could show examples of bold, italic and underlined text.

For procedures, we need to tell users what the procedure does, any prerequisites, why a user would (or would not) perform the task, and what the end result is.

Elementary, My Dear Reader

So what are the elements in a procedure? In a procedure, a user performs an action on an object, with some specific result. We could therefore list the elements as:

[user] [action] [object] [result]

So, for example, when a user updates a file:

• the action is the process of updating the file
• the object is the file
• the result is an updated file

Let's keep this mind for now and look at overviews. In a conceptual overview, a user reads an explanation of a concept and then, we hope, comes to understand that concept. We could therefore list the elements of a conceptual overview as:

[user] [concept] [understanding]

For example, a user reads an explanation of a database, and then comes to an understanding of what a database is and why they would use or create one.

All Together Now

Bring these two list of elements together, we get:

Procedures: [user] [action] [object] [result]
Overviews: [user] [concept] [understanding]

We can remove [user] from both lists. The user is the receiver of the document, but is not actually part of the document.

We now have:

Procedures: [action] [object] [result]
Concepts: [concept] [understanding]

[action] can be replaced with the more general [explanation]. When you define an action or step, you are really creating an explanation for that step.

[understanding] can also be replaced with [explanation]. The user understands, but the document explains.

We now have:

Procedures: [explanation] [object] [result]
Concepts: [explanation] [concept]

[result] could be more generically referred to as [state]. That is, in a procedure, an object moves from one state to another: a field is completed, a record is updated, a document is printed, and so on.

[concept] can also be generally referred to as an [object]. Although concepts can cover tangible items such as files, fields, and records, they can also apply to actions such as printing, saving, and copying. The action becomes of the object of the explanation. So whether you are describing a thing or non-thing, that item becomes the very object you are trying to explain.

We now have:

Procedures: [explanation] [object] [state]
Concepts: [explanation] [object]

At this point, it would be tempting just to simply remove [state], thereby making both lists of elements identical, and solve this puzzle. However, [state] is such an important aspect of documentation we cannot eliminate it. Instead, let's see if there's a way to add [state] to concepts.

State of Grace

What happens when a user understands a concept? The user moves from being in a state of ignorance to a state of awareness. However, we've already said that the user is not actually part of the documentation, only the object is. From the object's point of view, it moves from being in an unknown state to a known state. That is what an effective conceptual overview must do.

We can therefore add [state] to concepts and derive the solution:

Procedures: [explanation] [object] [state]
Concepts: [explanation] [object] [state]

That is, all documentation consists of these three basic elements in various forms:
[explanations] [objects] [states]

Does this have any practical application? Well, it can serve as a high-level checklist of whether a topic has been effectively written.

Specifically, if a topic does not clearly:

• identify and define an object
• offer a clear explanation of the concept or task
• indicate the change in state of the object (for a task) or actually change the state of the object from unknown to known (for an overview)

then the topic has failed.

So there you have it - a rudimentary theory of everything for documentation. And we only needed two dimensions to do it.

Read More

H1N1 A1 Confusion

The media's endless drive for ratings has us all convinced we're about two minutes away from certain death. To be sure, the H1N1 virus (the artist-virus formerly known as "Swine Flu") can be lethal. But let's have some perspective: more people will die from the regular flu than this nasty variant. More will also die from car accidents, obesity, alcohol, smoking and many other plagues, but why let relevant comparisons get in the way of a juicy news story?

To Save Your Life, Please Take a Number

The latest news concerns the vaccine production problems. Contrary to earlier reports where the various levels of bureaucrats assured us there would be plenty of vaccines for all, there's actually a severe shortage. Persons not in one of the "priority groups" need not apply for the antidote. Pregnant women, children and health care workers on the lifeboats first, please. As for the rest of us - not to worry - we'll have that iceberg removed in no time.

Great Expectations Not So Great

Now, imagine if the government had stated at the beginning only a limited quantity of the vaccine would be available. They would still have been criticized, but not to the same degree. The problem was a high expectation was set, and very badly went unmet. The end users (the public) don't care whose fault it was. All they know is they and their family are not getting their shot.

We can learn from this in the business world. Never set expectations too high, for if you miss them, you'll be a failure no matter how great a document you deliver. Always under-promise and thereby over-deliver. If you think it'll take N number of weeks to produce the guide, substitute 2N for N. That is, double the time you think it will take. The worst that can happen is you'll get it in "early".

To Vaccinate or Not to Vaccinate? That is the Query

The second major H1N1 controversy is whether one should even receive the vaccine. On the one hand are the government and medical authorities imploring everyone to receive the shot. On the other are various citizens concerned about the contents of the vaccine and its possible side effects. Unfortunately, this is a digital decision - 0 or 1. You either get the shot or you don't. You can't be a little bit pregnant, and if you are, congratulations: you're at the head of the line.

Confusion is poison in a document. It is the drop of oil in an otherwise pristine bottle of Perrier. It is to be avoided like the H1N1 plague. One way to inoculate your docs against it is to banish uncertain words such as: might, may, could, and perhaps.

For example: don't say:
Depending on your document type, some of the following tabs may not appear on the Properties dialog box.

Instead, explicitly state which tabs appear for each document type, for example:
For letter file types, the Main, Paper and Recipients tabs appear.

Certainly Uncertain

Even with this simple tip, you'll still encounter confusion and uncertainty when developing your docs. Often it's a case of one SME saying one thing, and another SME saying the exact opposite. If the issue is complex enough, the only solution is to lock both of them in a room together with you as the arbitrator, and not leave until the truth is found. (I've found faking flu symptoms and threatening to cough on both SMEs helps to quickly expedite the discussion.)

Sometimes the final answer you arrive at is different than what any of you envisioned. Those are the glorious moments in our profession. They validate our worth as information developers. They show we add real value to the company. And they give us a real shot in the arm.

Read More