Six Things That Should Be Single Sourced

Single-sourcing, as we all know, is the art and science of using a single repository of information to produce multiple outputs. Typical examples include creating a PDF and online Help project from one source, or creating different versions of the same manual for different user types. It is one of the most valuable weapons in the battle to tame the information monster.

Of course, single-sourcing has been used for many years in other industries, particularly in programming. Developers use object-oriented programming to create re-usable modules (or "classes') of code. These modules are stored and maintained in one location, and used as necessary. Object-oriented programming is called "OOPs" for short. "OOPs" is also something programmers like to say when they realize an entire module is missing from an application that has just been released.

A Single-Sourced World

Single-sourcing has even been applied to industries outside of software. Car makers, for example, design their cars so that a spark plug for one engine will fit in other engines. This process of standardization is a form of single-sourcing that reduces maintenance and assembly costs, although probably won’t be enough to save General Motors – more on this later.

Single-sourcing is such a powerful idea that I see no reason why it can't be applied to other areas:

1. Light bulbs – Have you been to a hardware store recently? There’s about 200 different kinds of light bulbs to choose from. Halogen, fluorescent, incandescent… Remember the good old days when there was just one shape of light bulb, and the only variance was the wattage? Have you ever tried to change a halogen bulb? It’s easier to put braces on a mosquito. I say single source it – one light fixture for all.
2. Screws – Continuing on the subject of hardware, can someone explain why there are so many different types of screws? There’s the screw head drive patterns: slotted, Philips, raised, torx, hex, Robertson, tri-wing, torq-set, spanner, and my personal favourite, pozidriv. Additionally, there are different head shapes: pan head, button or dome head, round head, truss head, flat head, oval or raised head, bugle head, cheese head (I’m not making this up), fillister head, socket head (what we call an uncooperative reviewer) and headless (like the horseman). To further complicate things, there’s metric and non-metric sizes. To paraphrase Murphy’s law: the odds of having the correct screw at the correct size and shape and the correct tool for it are inversely proportional to the importance of what you are trying to attach. Surely some of these shapes, patterns and sizes could be amalgamated. Otherwise, we’re screwed.
   
3. Cars – As indicated earlier, the Big Three automakers don’t seem that big anymore, with Ford and GM posting record losses, and Chrysler probably not far behind. Eventually, these three companies may have to merge - single-sourcing at its finest. But why stop there? Why not just have one car company throughout the world? Yes - it would be a monopoly, but think all of the money that would be saved in research, marketing, advertising and so on. Far fewer parts would have to be manufactured and maintained. Mechanics would just have to know how to work on a few different cars instead of hundreds. Buying a car would be easier and faster because there would be fewer choices. We could give this new car company a catchy name, like “Toyota” or “Honda”.
   
4. Language – What’s with all these people that don't speak English? Everybody knows it’s the official language of the universe. Want proof? Watch any Star Trek episode - no matter what planet is visited, its inhabitants speak English. Do you know how much money is wasted translating information into various languages? The time and effort to learn other languages is staggering. We desperately need to single-source language – everyone speaks English from now on. And if you don’t like it, well, hasta la vista, baby.
5. Political parties – It’s going to cost $270 million dollars to have an election. Didn't we just have one? What a waste. Let’s avoid this nonsense now and forever and just have one party. Think of all the money and time we’d save! No more election campaigns. No money wasted on the “official” opposition. Everyone would do their own thing and we’d leave the government to do theirs, without having to be bothered every few years putting a silly little 'X' on a piece of paper.
   
6. Countries – And since we’re on the subject of politics, why do we need so many countries? Couldn't some or all of them be merged? Instead of having to pay for hundreds of governments and leaders, we could just have one. Everything would be consistent and standard from country to country. Travel would be easier because you'd no longer need a passport and everyone would speak the same language.

I Have A Dream, and it is Single Sourcing...
This is the vision. This is the dream. Soon, we will be able to celebrate the glorious anniversary of these single source directives. We will create, for the first time in all history, a garden of pure ideology. Where each worker may bloom secure from the pests of contradictory and confusing truths. Our unification of thoughts is more powerful a weapon than any fleet or army on earth. We are one people, with one will, one resolve, one cause. Our enemies shall talk themselves to death and we will bury them with their own confusion. We shall prevail!

Read More

The InfoDev Political Spectrum

Politics is always in the news, therefore it's always a good time to explore it, and the politics of information development.

Do you remember learning the so-called "political spectrum" high school? It looks something like this:

<--- Left Center Right --->

Expanding this a bit, we get:

<--- Communism - Socialism - Liberalism - Centrist - Conservatism - Far Right - Fascism --->

A more practical view is:

<--- Crazy - Normal - Crazy --->

Left/Right is Dead/Wrong
This "left/right" paradigm is extremely outdated. It's a 200 year old model that originated during the French Revolution, and referred to the seating arrangements in the French Legislative Assembly. Conservative Royalists sat on the right; liberal Montagnards sat on the left.

Much has changed in 200 years. To call this spectrum a gross-over simplification would be a gross-over simplification. It may have been appropriate to describe the political forces in emerging democracies, but in today's world, it's more outdated than Windows 1.0.

Tech Writing Rule #1 - Define Your Terms
To see what the problem is, we need to do what we as information developers do best: find out the real meaning behind the terms. What exactly does it mean to be a "liberal" or "conservative"? (Please note that throughout this explanation, I always refer to liberal or conservative in a generic sense, not to any specific party.)

In a nutshell, we could say that:

• A liberal favours more government control on economic issues, but less control on personal issues.
• A conservative favours more government control on personal issues, but less control on economic issues.

Personal (or social) issues include: freedom of expression vs. censorship, abortion, marriage & family, drug use, culture, religion and the draft.

Economic issues include: taxes, government regulation of business and free trade.


Filling the Gap

Now, if you have any experience in gap analysis, you should be able to see the problem with the left/right spectrum. "Liberal" and "Conservative" cover only two of four possibilities: the two other combinations are completely missed, specifically:

• Someone who favours less government control on both economic and social Issues.
• Someone who favours more government control on both economic and social Issues.

Mr. Nolan's Opus
To address these exclusions, in 1970, David Nolan, founder of the U.S. Libertarian Party, developed a political spectrum with two axes instead of one. Being a modest person, he called his invention the Nolan chart.
The Nolan chart looks like this:

















The horizontal x-axis represents the degree to which a person believes in "economic freedom": the more to the right you are, the less restrictions you think government should place on economic areas.

The vertical y-axis represents "personal freedom". The higher up you go on this axis, the less governmental restriction you advocate on personal areas.

The result is the above square divided into four quadrants:

• the upper-left quadrant represents the traditional political left
• the lower-right quadrant represents the traditional political right
• the upper right quadrant represents Libertarians, people who favour less government control in both personal and economic areas
• the lower left quadrant represents Populists, people who favour more government control in both personal and economic areas (this group is also called authoritarians, statists and wackos)

Critical Acclaim

This chart has its critics. Some say it over-simplifies the political spectrum, and is biased towards its creator's Libertarian views. The terms "political freedom" and "economic freedom" are biased and can mean different things to different people. A more objective term might be "the degree to which less government control is favoured", but that's a bit of a mouthful. Still, relative to the old left/right model, the Nolan chart is a vast improvement, in that it at least acknowledges other points of view.

Documentation Dimensions

How can this model apply to us? Well, if you could isolate the two main properties, beliefs, philosophies, approaches or ideologies within information development, you could create such as spectrum for information developers. Each dimension would have to reflect beliefs in which there would be two opposing but equally valid viewpoints. In essence, each dimension would have to represent a "struggle" or "conflict" between these two views, in much the same way that many people struggle with opposing beliefs on both personal and economic issues in the political spectrum.

The Devil is in the Details

Let's start with the first dimension. The main issue that I think we all struggle with is: how much detail should we include in our documentation? How much is enough? Do we tell our users everything they possibly need to know? Or do we include only what we think are the most important facts? Do we create documents that are large and complete, but may be difficult to explore, manage and navigate because of their size? Or do we create documents that are as small as possible and quicker to navigate, but possibly exclude necessary information?

The fact is, one can always make a document simpler or more complex. It is simply the nature of information. You can always add more, or take away more, and knowing when to add and remove is the perhaps the most important skill an information developer can possess.

Keep it Complex, Stupid

With this in mind, we can start to develop the first dimension of our two-dimensional spectrum: complexity, which looks like this:

<---------- Complexity ----------->
Simplifiers ------------ Detailers

On one side are the simplifiers, people who value simplicity above all. They believe only necessary and valuable information should be contained in a document, and that all else should be excluded.

On the other side are the detailers, those who believe that you can never have "too much information".

In other words:

• Simplifiers value simplicity over completeness.
• Detailers value completeness over simplicity.

Just as in politics, there is no right or wrong here. Reasonable people are entitled to hold contrary beliefs. In fact, we are all both simplifiers and detailers, however if your really examine yourself and your work closely, you'll find that you tend to be on one side of the spectrum or the other.

A Model of Modularity

Complexity is the first aspect of our spectrum: what should the second one be? This is a little trickier: it is modularity, the degree to which we create, store and reuse text objects. Whereas complexity deals with how we view information, modularity deals with how we actually develop and manage information. We can view this dimension as:

<------------Modularity----------->
Consolidators ---- Separators

Consolidation Anxiety vs. Separation Anxiety
Consolidators believe that all pieces of information should be consolidated into as few places as possible, and avoid breaking text up into pieces. They feel that while reusing text has its advantages, it can be difficult to maintain, and creates the possibility of boxing one's self into a corner when it comes to reuse. When consolidators do re-use text, the text blocks tend to be large and stable, for example, copyright and legal information. Consolidators value the flexibility of being able to change most text anywhere, without causing any undue effects throughout their documentation.

Separators believe that information needs to be separated into its component parts. Common text within a document or throughout a documentation set is stored as reusable pieces, so that if a change is made in one piece, it will automatically propagate to the others. Separators recognize this requires more work in the short term, as text objects have to be planned, created and managed very carefully. The objects may need to be broken up further still, requiring extensive rework. However, separators consider the payoff worth it - a modular documentation set.

To sum up:

• Consolidators value flexibility over reusability.
• Separators value reusability over flexibility.

Again, there is no right or wrong position here. I have worked on projects where reusability was neither required nor practical, and others where it was absolutely essential. Some documents may require more modularity than others. Even in modular projects, it's always a struggle to decide just how large to make the text object. It is this struggle that define the modularity dimension.

Full Spectrum Analysis

Putting these two dimensions together, we get the full information development political spectrum:



Complexity (the horizontal x-axis) represents the degree to which you believe information should be complex and detailed, instead of simple and elegant. The more to the right you are on this axis, the more you favour detail over simplicity.

Modularity (the vertical y-axis) represents the degree to which you believe information should be separated into reusable parts. The higher up on this axis you are, the more you think content should be modularized.

What's Your Sign?
Summing up the four quadrants:

• Consolidating Simplifiers (bottom left) believe documentation should be as simple and consolidated as possible.
• Consolidating Detailers (bottom right) believe documentation should be as detailed and consolidated as possible.
• Separating Simplifiers (top left) believe documentation should be as simple and modular as possible.
• Separating Detailers (top right) believe documentation should be as detailed and modular as possible.

I see no conflict in believing that documentation should be both simple and modular, or, alternatively, both complex and consolidated. Simplicity refers to what the user experiences, whereas modularity refers to the information that the technical communicator sees, creates and manages. A simple document, therefore, can be very modular, and a complex document can be consolidated.

Beyond the Fourth Dimension
Complexity and modularity are the two dimensions we have explored on the technical communication spectrum, however there are many others, including:

• the importance of content vs. form
• using text vs. illustrations

Others dimensions reflect the specific type of technical communicator you are:

• full-time vs. part-time
• lone writer vs. team writer
• your level of experience: beginner vs. intermediate vs. senior
• your specific role: technical writer, information developer, information architect, usability specialist, manager, editor, content manager, technical illustrator, teacher, web designer

Other dimensions include particular areas or documentation types that you may favour working with or in:

• internal vs. external documentation
• technical vs. non-technical documentation
• online Help vs. PDF files vs. web-based documents
• documenting for beginners vs. documenting for advanced users
• documenting theories and overviews vs. documenting procedures and examples
• standard documentation vs. training documentation vs. support documentation
• the specific industry in which you work: software, hardware, medicine, engineering, manufacturing, aviation, military, biotechnology, government, and so on

The technical communication universe is indeed a complex multi-dimensional one, large enough for all tech communicators of all political stripes.

See you on the spectrum...

Read More

The Top Six Reasons Why You Shouldn't Write for the STC Newsletter

As both the newsletter editor and a regular columnist, I strive to encourage others to contribute to the newsletter. However, since people rarely do what you tell them, and often do just the opposite, I therefore present:

The Top Six Reasons Why You Shouldn't Write for the Newsletter

1. You have nothing interesting or meaningful to write about.
   
   If you wrote something interesting about yourself, your work, or our profession in general, it would mean that you had a unique experience or viewpoint that would be worth sharing. You certainly wouldn't want to admit that.
   
2. People might think you are strange. It's important to spend your life worrying about what other people think about you. One should always strive to be the type of person others expect you to be, rather than who you are as an individual. Of course, this can be a problem if you have a wide variety of friends, but the solution is simple - don't have any friends. Alternatively, you can simply bend yourself into a pretzel to match others' expectations of you. The last thing you want to be called is weird, strange, odd or eccentric.
   
   
3. You don't want the publicity or the chance for your work to be attacked.
   I myself am getting attacked constantly. Just the other day, a group of angry tech writers tried to lynch me because they said I was using too many nouns. Tech writers are certainly notorious for their violence throughout the ages - we all shudder when remembering "Ivan the Terrible Tech Writer".
   
   
4. If you write an article, you will have to write one each and every month.
   As the Newsletter Editor, I am also commander-in-chief of the Communication Times goon squad. This is a gang of 6-8 very large tech writers who live in caves and come out at night to harass and beat senseless all writers who do not commit to me in blood to write an article each month.
   
   
5. It will take time away from your other important activities. Here are some important tasks you would have to cut down on if you wrote from the newsletter:
• watching Star Trek reruns
• eating large quantities of potato chips
• picking the skin between your toes
• reading People magazine
• watching sporting events
  
6. There's no practical reason to do it.Writing articles does not make you a better writer because you don't have to use any writing skills. Also, you would never want to include in your résumé that you wrote for a professional association's newsletter. Potential employers might actually think that you care about what you do, so much so that you took time out of your busy schedule to write articles about your profession. The last thing you want is for an interviewer to think you are passionate about your industry. Also, even if adding this to your résumé improved it, it could lead to a higher paying job, and you are above such materialistic concerns.

So there you have it - the six reasons why you should not write for the newsletter. Therefore, I beg you, please, do not email me your article ideas.

Read More

Wikipedia and the "Informalation" Revolution

Wikipedia is one of the most extraordinary and fascinating websites you will ever see. It is a vast on-line encyclopedia of knowledge, with the distinguishing feature that any one can edit (and informally discuss) any of its topics. And edit they do: thousands of users (myself included) regularly create and update Wikipedia’s content. Changes are continually being made every minute of every day. In this sense, Wikipedia is a giant, living, breathing, and growing documentation lifeform.
Wikipedia was launched in 2001. It now contains over 1.6 million articles, over 660,000 of these in English. Encyclopædia Britannica, by comparison, as only 120,000 articles. But is "more" necessarily better?

Close Your Mouth and Open Your Mind
This is the great debate currently raging between Wikipedia’s advocates and its critics. Wikipedia’s supporters argue that an "open source" structure in which anyone can perform updates will lead to the highest quality of information. Wikipedia has similar structure to Linux, an open source operating system which anyone is free to modify. Supporters also point out that unlike traditional print encyclopedias, or even software-based ones such as Microsoft Encarta, Wikipedia is continually updated in real-time, therefore much of the information is extremely relevant and timely.

Wikipedia’s critics, including, not surprisingly, one of its main competitors, Encyclopædia Britannica, argue that Wikipedia’s information is unreliable, not formally fact-checked, and biased. However, despite these criticisms, Wikipedia remains a powerful and well-used source of information for thousands of individuals. As information developers, we should be heartened by the fact that so many people care enough about accurate and complete information that they are volunteering their time to create the largest encyclopedia in history.

Officially Unofficial
Wikipedia has proven that there is real demand for information outside of "official sources". The need has always been here, as shown by the success of the "Dummies" and "Idiot’s" books – unofficial guides on a wide variety of topics. In addition, there are the thousands of other unofficial books, websites, discussion groups, newsgroups and so on that are a source of valuable information to millions. The fact that this information is not supplied by the traditional, formal or standard sources is irrelevant. People will take informal, unverified information over no information every time.

Since, we, as information developers, are the main creators of official information, we must be aware of this new tide of informal information, or "informalation", as I like to call it. We cannot let ourselves fall into the trap, as Encyclopædia Britannica has done, of saying that informalation has little or no value, so it can just be ignored. The success of Wikipedia has shown we cannot ignore it.

An Official Spectrum
We must start by recognizing that although both official and informal information sources exist, much information actually falls on a spectrum between these two extremes. At one end is the official and formal documentation and information issued by a company. At the other end, is the unofficial information typically created by end users. Using Microsoft software as an example, we would have, from most formal to least:

• Formal sources: documentation, online help, Knowledge Base
• Less formal: Microsoft newsgroups, Dummies and Idiot’s books
• Informal sources: user websites, personal notes, emails and discussions, information about "hacks" and workarounds

Most people will use many of these sources: it is rare that someone will use only the formal ones. As one moves from formal to less formal, the timeliness and quantity of information may increase, but the accuracy and quality may drop. This is the trade-off, though, that people are willing to make.

So, should we all stop being formal information developers and work for Wikipedia? Of course not – Wikipedia is a volunteer organization, and we still have to eat. Also, there will always be a requirement and demand for "official" information.

Free Range Documentation
Instead, we must recognize and accept the fact that no matter how good the documentation we create, and no matter how many others have reviewed it, if you were to take a document and distribute it to every one of your end users in such a way that they could easily change it, they would change it. It is simply impossible to create a document that cannot be further improved if everyone was allowed to be a reviewer. But wouldn’t this create total chaos? How could a company control and manage its documentation if everyone was allowed to change it?

Some companies, including Microsoft and Adobe, offer partial solutions by allowing and even actively encouraging feedback on specific on-line knowledge base topics. The problem is that the feedback is sent directly to the company, and no-one else can see it, unless and until the company decides to incorporate it into their documentation, and then re-post it. Another method companies use is to create various discussions groups. Some of these are formally supported, others or not. The problem is that it is often difficult to locate specific topics within these groups, but more importantly, there is no practical connection between the discussions in these groups and the source documentation. Both are completely independent of each another – changes in one area are not reflected in the other.

Formal vs. Informal Info - Can't We All Just Get Along?
A better approach is to more formally recognize that informalation exists and has a purpose, and integrate it directly into our formal documentation. In much the same way that Wikipedia (although itself an "unofficial" information source) has both a formal topic listing, and a corresponding informal "discussion" page for each topic, I can imagine a future in which all formal documentation appears online with a corresponding "informalation" page. This page could include various user feedback and comments. Companies could still decide whether to display specific informalation pages, or even specific comments, or they could simply issue a warning saying that the information on the informalation page is not supported but is here for your informal reference only, and that you cannot hold the company liable in any way. This is much like the EULA (End User License Agreement) that you are supposed to read when installing software, but which nobody reads anyway!

Closing the Loop
Eventually, a process could be developed to automatically send the comments to the information developer, who would then update the source documentation accordingly. This is what is known as a "closed looped" system, in which the information is continually released, commented upon, updated based on these comments and then re-released in an endless loop. It embraces the Japanese principle of Kaizen, which roughly translates into "the science of continual improvement".

The only hitch in this info-utopian vision is, of course, the time, effort and money it would require to create and maintain such a system. Currently, it may be suited only to companies that have a limited number of users. But it’s a start. The potential improvement to an information set would be enormous. Such a system may be years away, but Wikipedia may turn out to be the "killer app" of the Internet that inspired it all.

Wikiing the World
And for those of you who think that because Wikipedia only covers general knowledge so it won’t affect us, see Wikipedia sister projects, including a dictionary, textbooks, quotations, source texts, news and another type of book you may have heard of: user manuals.

Read More

The Matrix - Redocumented

The concept behind the film “The Matrix” is greater than the film itself. If you are one of the three people on the planet that who have not seen this film, here’s a quick summary:

In the future, machines have conquered the world and need electric power to stay alive. They have enslaved humanity in a giant computer-generated simulation called The Matrix, and are using humans as batteries for their power source. The Matrix appears so real that no-one knows they are in it. However, some people have escaped the Matrix and are battling the machines to free humanity.

It’s a fantastic premise, unfortunately the film gets bogged down in endless action sequences and bizarre dialogue. It’s as though the directors input a science-fiction film, a martial-arts film, and an artsy philosophical film into a computer, scrambled them all together, and then spit something out.

The Matrix - Deconstructed

Much of the film involves humans battling the machine within the Matrix. I could never really understand this premise. Why do machines have to fight humans within a computer program? Wouldn’t the machines be sophisticated enough to physically locate their human opponents and annihilate them the old fashioned way? And even if you do accept the idea that the machines have to fight humans within the Matrix, why couldn’t the machines simply take on a massive, all-powerful form in the Matrix (rather than the relatively small humans forms which they do take) and quickly obliterate their human enemies? Perhaps the answers to these questions are in The Matrix Technical Guide, but I have been unable to obtain a copy.

Morpheus, Technical Writer

Another annoyance is the extreme Zen-like dialogue in which the characters blather on, especially Morpheus. He speaks in endlessly confusing allegories, metaphors and allusions, and everyone is too sheepish to ask “What the hell are you saying? He’s not exactly a Plain English advocate.

Morpheus would have been a most annoying tech writer. I imagine a conversation between him and his manager:

Manager: Morpheus, I had some questions about that last draft you sent me.

Morpheus: The answers you seek are all part of the questions you already know.

Manager: Uhm, ok, whatever…First, there seems to be some blank pages here.

Morpheus: Are the pages really blank? Or is it your mind that is “drawing” a blank.

Manager: Just get me the missing content. And another thing, this index is not in alphabetical order.

Morpheus: Why must things be in alphabetical order? Is the universe in alphabetical order? Does “Earth“ come before “Saturn“?

Manager: Well, I’m giving you an “order” – fix it. Also, there’s a procedure here that doesn’t make any sense.

Morpheus: You need to stop trying to read it and read it.

Manager: Look – I need all this fixed by the end of the week.

Morpheus: Do you really believe that documentation is limited by something as non-existent as time?

Manager: That’s it – you’re outta here! Get your things and go!

Morpheus: I was never here…and neither are you.

Neo: Whoa….

* * *

Reality...What a Concept

There were three Matrix films in total – can we call these “The Matrices”? In any case, these films do raise an important philosophical question: what is reality?

The fact is, it is impossible to prove that we do not live in “The Matrix”. We could all actually be unconscious, floating in tanks somewhere, all connected to a massive simulation of the world that we think is the real world. Or perhaps we all came into existence this very second, with all the memories of our life up to this moment downloaded into our minds.

Why then, would so few people accept these scenarios? I think it is because deep down, people naturally crave simplicity. Whenever there is a choice between a simple solution or a complex one, most people will choose the simpler one.

Shaving with Occam's Razor
This idea is reflected in a principle called Occam's Razor, which states you shouldn’t make any more assumptions than you need to in order to explain something. When there is more than one explanation available, the simplest one is preferred. In other words, one should always apply the K.I.S.S. principle: Keep It Simple, Silly.

Applying Occam's Razor to information development, we would say: if there is more than one way to document something, choose the simpler way. The ability to remove unneeded information is as important as the ability to create useful information. It is so important that there are people who perform only this task – they are called editors. However, all information developers must also be editors, at least part-time.

The Science of Reality TV
Scientists continually strive to apply the principle of Occam's Razor. In fact, it is science that has often completely changed our basic assumptions about the nature of reality. Atoms have been revealed to be over 99.999% empty space. That is, most of everything that we think of as real or solid is literally nothing. We perceive things to be solid because our senses are not acute enough to detect the emptiness: our minds fill in the blanks. You can easily experience this by seeing the pixels of a TV image up close, and then moving away from the TV. As you back away, the dots merge together to form a vivid image.

We therefore see one reality when viewing the screen up close: the various pixels flashing and flickering. As we move away, we see another reality: the moving images of a TV show. This is the "reality" we see on TV.

Or is it? All TV shows (even so-called "reality" shows like Survivor) are carefully planned and directed. They all represent a simulated or virtual reality. Reality is what happens when you turn off the TV.

Waiter, There's Too Much Reality in My Soup (or maybe not enough)
Strangely, at the same time our minds are adding the missing pieces, they are also filtering out the excess data that we perceive; the data that we cannot process because it would overwhelm us. Therefore our minds are doing two seemingly contradictory actions: they supplement what we perceive with extra information, and simultaneously screen out other information. This means that we actually do live in “The Matrix”, because the world we perceive is not the real world, but is both an abridged and edited version of it. It is a house that has been heavily renovated and reconstructed, some parts added and others taken away, leaving what we perceive as the real house.

The big question is: if you could remove these additive and filtering processes, what would you see? What would the real reality look like? We can’t know, because these processes do not stop until you die, and no dead people have come back to document what they’ve seen.

Tech Comm - The New Math
In technical communication, there are also additive and subtractive processes at work. When users read instructions or information, they screen out what they think they don’t need, often focusing in on the key areas of information they think they require. At the same time, they are adding their previous experiences and ideas to the information they are absorbing, sometimes with unexpected results.

For example, many users are used to the idea of an “undo” function in software, a function that allows them to reverse a previous operation. They may assume they can “undo” anything, however sometimes this is not the case. They may read a procedure about how to delete an object, thinking they can undo it. They are literally “reading in” their experiences and assumptions into the text. When they learn they cannot undo a deletion, their perceptions clash with reality, and that is called pain!

The Document Hunt Begins
So, for both documentation and reality in general, what we perceive is what our minds have been programmed to perceive. In otherwords, perception is reality. This has huge implications for information development. If perception is reality, then nothing really exists in the traditional sense of the word. In fact, it is especially documentation that does not “exist”. You are currently reading this document online – the question is: where is the document? Is it on the screen? If so, if you turn off the screen, does the document cease to exist? No, because once you turn the screen on again, the document appears. Even if you shut down your system completely, others can still read the document.

In fact, a document, or any computer file, or even a TV show, can be on one screen, on no screens or on many screens at once, and still exist. What kind of “existence” is that? There is simply no parallel in the regular, non-electronic world. (However, as we will explore in future column, there are parallels in the subatomic world.)

Where, oh Where Has My Document Gone? Where, oh Where Could It Be?
Continuing our search: is the document on a hard drive? If you were to crack open the hard drive, would you see the document? No – so where is the document?

The answer is the same: perception is reality. Just as the real world exists because we perceive it to exist, so too does the document exist because we perceive it to exist. Our eyes receive the various shapes of letters, screen out what is not required, process the information and then feed it into our brain. No perception – no document.

Time for Your Annual Meta-Physical
It is no coincidence that science and philosophy can teach us much about information development. As I described in a lecture last month, information development, science and philosophy are all different attempts to discover the truth. They do this by modeling reality in different ways: documentation describes a thing or process, science describes the physical world, and philosophy describes the meta-physical world.

So as an information developer, you must always ask yourself: how far down the rabbit hole are you willing to go, to document the concept we call reality?

Read More

The Responsibility Game

The Gomery inquiry investigating the government's "contracts for donations" scheme is currently one of the most popular reality-TV shows. However, it has at least one unique feature: instead of the various players voting each other off, we the people get to vote them off, and replace them with another group of players who will get to play the exact same game.

One of the buzzwords in this affair is "responsibility". Everyone is screaming: "Who's responsible for this heinous crime?" Responsibility is also a very big thing in the business world, and since we as professional technical communicators are part of that world, we need to be concerned about it.

Organizations function well when everyone knows what they are responsible for, and when everything has someone responsible for it. Companies get into trouble when something that should happen does not because no-one thinks they are responsible for it.

As information developers, we are responsible for producing documentation. But how much responsibility should we bear? To answer that question, it's time to play…

The Responsibility Game
(Lively introduction music)

Announcer: Welcome to The Responsibility Game, with your host, Frank Ferrari. And now, heeeeeeeeeeere's Frank!!
Frank Ferrari: Thank you. Welcome to this week's edition of The Responsibility Game, where we answer the question:
Audience: Who's responsible?!
Frank: Last week, we found out that the government was responsible for all the lousy weather we've been having, and for all those socks you lose in the washer. This week, we're gonna look at something a bit more serious: bad documentation.
Audience: Ooooooo…
Frank: Yes - we've all seen it - manuals that don't make sense, pictures that don't match up with the instructions, assembly instructions that make you want to kill someone, or at least maim them severely. We've all felt the pain, and today we're gonna doing something about it by finding out…
Audience: Who's responsible?!
Frank: We're speaking today with PillowHeads Incorporated, a company that makes software that does…something. We'll be talking with some of the various workers there, through a live, televised link, starting with Nero, the tech writer. Nero, are you there?
Nero: Yeah, I'm here Frank. Love your show!
Frank: Thanks. OK, Nero, your latest user guide was released, and we've spoken to some of the end users, and we're gonna tell you what they said.
Nero: (nervously) OK… I'm listening…
Frank: The verdict is….they loved it! They said it was the best manual in long time. How do you feel?
Nero: Wow - that's great. I'm dreamt about this moment ever since I was a fetus…
Frank: Hey, you're making me all teary-eyed, kid. But what our audience wants to know is…
Audience: Who's responsible?!
Nero: Well, not to boast or anything, but since I am the tech writer and I wrote it, then obviously I'm responsible for it. I had some help in getting the info I needed, but then I was the one who actually put the thing together, so wouldn't that make me responsible?
Frank: You can't argue with such air-tight logic. But let's hear what others have to say. Let's talk to one of those people Nero mentioned helped him get the info he needed - Ivan the Programmer, also known as Ivan the Terrible. Ivan, you've heard Nero say that he's responsible for creating this fantastic document - what do you say?
Ivan: Nero good man. Very strong, like bear. But I tell him what he need to know. Me responsible!
Frank: Eloquently stated, Ivan. Now let's move up the food chain and talk to Nero's boss, Manfred. Manfred - you've just hear that the client loves the new document - we wanna know:
Audience: Who's responsible?!
Manfred: Nero did a great job in putting that manual together. He worked hard and did what he had to do. But since I was the one who hired him and taught him almost everything he knows, I'd say that ultimately, I'm responsible. If hadn't hired him, we wouldn't be talking about this now.
Frank: Good points all around. Let's keep moving up, shall we? We're talking next with Manfred's boss, the VP of the department, Herman. Herman - what are you thoughts? Who's responsible for this great document?
Herman: Well, I would agree that Nero did a good job. But if we take Manfred's logic, then I would say I'm responsible, because I hired Manfred, and I only hire the best people - people who are able to in turn, hire more of the best people. Because people are our greatest asset, after our inventory and cash reserves.
Frank: Well, I gotta tell ya - this is the first time I've been this undecided about who's responsible. Everyone is making a solid case. But we're gonna get to this bottom of this, by going straight to the top. Our last guest is the company president, Bartholomew. Bart - you've heard everyone's opinion. You're the top guy. Who do you think is responsible for the manual?
Bart: Let me be frank, Frank. I've heard a lot of talk today. Everyone wants to take credit, and I can understand that. I feel what everyone's saying. That's my weakness - I feel so much sometimes, it hurts. But I founded this company. I created it - it's my baby. I raised it. I fed it. I taught it to walk and do math. And I simply cannot allow others to take credit for my baby. No one's going to kidnap my baby. None of these people would be here if I hadn't given birth to this baby. So, as a parent of this company, I am ultimately responsible for everything my baby does, good and bad.
Frank: Wow. What can I say? I'm speechless. Everyone has made a very compelling argument. There's just one small problem - this whole episode has been a scam! The truth is: the client HATES the document! So we wanna know:
Audience: Now who is responsible?!
Bart, the president: It's Herman's fault - I never should have hired that guy!
Herman, VP: It's Manfred's fault - I never should have hired that guy!
Manfred: It's Nero's fault - I never should have hired that guy!
Ivan: Nero bad! Bad tech writer! Must kill! Kill tech writer! Kill tech writer!
Bart, Herman, Manfred and Ivan: Kill tech writer! Kill tech writer!
Nero: What the …? Hey, what are you guys doing? Put that thing down! Help! Frank! Help me!!! I need…
Frank: Well, we seemed to be having some technical difficulties….Anyway, I want to thank all our guests for being on the show, and thank our audience for finding out:

Audience: Who's responsible?!

Read More

Hockey Lessons

The term 'hockey fan' does not apply to me. I simply cannot spend three hours watching a group of people skate around trying to insert a small, flat rubber cylinder into a mesh. (Hockey fans, please send all hate mail to abrooke@primus.ca)

In a Tech Writer’s World, I am the “thinking man’s” interviewer on the Sports Network, conversing with fans after a game:

Me: So, how do you feel about our team winning tonight?

Deranged hockey fan: Oh man! It’s awesome!! Wooo-hoooo!

Me: So you’re excited about the fact that a bunch of millionaire-strangers who don’t want anything to do with you were able to score more points than another group of strangers: how does this victory affect you on a daily, practical level?

Deranged hockey fan: Uh - go Leafs!!!! Yeah!!!

Me: Another insightful comment from the sports drones. Back to you, Frank.

Now, this is not to say that hockey games cannot be exciting. However, what generates this excitement is not so much the actual play, but the running commentary. In fact, we should have commentators for the documentation review process:

Announcer: Joseph generates the first draft. He passes it off to Andreychuk. Andreychuk toys with it, marks it up a bit, slides it off to Curtis, Curtis tries to read it, he can’t, slaps it over to Belfour, Belfour marks up a procedure, adds an overview, passes it over to Kariya, Kariya misses it, ends up with LaFleur, LaFleur makes some more changes, passes it back to Curtis, he still can’t read it, he shoots it over to Turgeon, Turgeon doesn’t want it, passes it back to Curtis, back to Turgeon, to Curtis - boy these guys really hate reviewing drafts - Curtis finally shoots it over to Dwyer, Dwyer’s holding it, looks like he’s scribbling something on it… let’s zoom in the camera bit… Looks like he wrote: “needs work”…ooooo.. the ref’s not gonna like that…

Referee: Penalty for number 32, Ken Dwyer – 10 minutes for vagueness and poor spelling…

Announcer: That’s gotta hurt. I always said he wasn’t a first draft player…

Still, as much as hockey itself does not interest me, the current labour dispute does interest me. In fact, for the first time in my life I actually find myself religiously reading all hockey news in the sports section of the newspaper. The idea of two sides, so tremendously apart, so unwilling to budge or compromise, so willing to drill holes through the other side’s boat, not realizing they are all on the same boat, is endlessly fascinating. And if I, a non-hockey fan find it fascinating, then people who are hockey-fans must be experiencing severe rupture of most of their internal organs.

Lessons Learned

So, you’re not a fool if you’re not interested in this dispute. But you would be a fool if you failed to learn the lessons from it:

Lesson 1: Terminology is everything.
One of the problems in this battle is that the two sides cannot agree on the meaning behind the specific terms in the negotiations. When you have one side saying that a specific proposal is a “salary cap”, and the other side saying it is not a “salary cap”, this doesn’t mean one side is “right” and the other is “wrong”. It indicates that they cannot agree on what a “salary cap” is. Is it a limit on what all players can make in the league? On what an entire team can earn? Is it, for practical purposes, a number so large that it could never be reasonably reached? Is there a time constraint on it? Can there be exceptions?

Documentation and software development face the same problem. An item or object in a program may go by different names. The same name may be wrongly applied to more than one item. What an item is or does varies depending on which SME you talk to. This leads to endless confusion and frustration for both technical writers and end users. One of the most important tasks in the documentation process is to clearly and consistently define what all elements are. Glossaries help tremendously in this task, which is why they are often very difficult to develop. You may find yourself having to forge many different opinions into one document, but the end result is a “rule book” that everyone can use when referring to the application.

Lesson 2: If something stops, it is forgotten.
The level of contempt most people have for both sides in the hockey dispute is palpable – you could cut it with a hockey stick. “Millionaires arguing with billionaires” is how this fight has been described.

What is happening now is quite remarkable, completely predictable, and the worst nightmare imaginable for both parties: people are beginning to getting used to the idea of no hockey. They are actually finding other things to do with their lives. I remember a few years ago, during other labour disputes, when neither hockey nor baseball games were taking place. In a letter to the editor, a father indicated he actually didn’t mind the dispute because it allowed him to spend more time with his family. Horror of horrors! What’s next? People might start meeting with their friends, reading, or god forbid, writing columns like this one. It’s just too painful to think about how far our civilization could advance if there was no more hockey to watch.

Doctors tell us that if you do not keep your muscles moving, they will atrophy, or grow weak from non-use. It took years for baseball to recover from its labour disputes, and it could take hockey even longer.

The lessons for technical communicators are two-fold. On an individual level, we must continually hone and expand our various skills. These include not just writing, but learning new tools, organizing, project management, SME interviewing, as well as general career management skills such as networking, job interviewing and resume-writing. As with hockey, we can never rest on our laurels; we must be continually moving, learning and adapting. Otherwise, we will atrophy.

On a company level, we must continually fight to show we are indispensable. Many companies would like nothing better than to get rid off all tech writers, QA workers and half the programmers. The only reason they do not is that they believe it would cost them more in the long run. We must be the ones to convince others that we are indeed indispensable, that unlike hockey, a company would never “get used to” having no tech writers; that this would create unimaginable pain for them, in the form of higher support costs, poorer documentation (if there still was documentation!), lower quality software (because we are no longer there to give objective feedback on usability), grumpier customers, lower sales, and ultimately, lower profits. We can make our case not just by improving things, but by showing those in power how we have improved things.

Lesson 3. Some things are so broken, they can only be replaced.

Most experts agree that if hockey does return, it will be a very different game under a very different league structure. In fact, it may be completely unrecognizable from its current form. Often things are so damaged, it is not even worth trying to “fix” them, but is cheaper and easier just to replace them.

A vivid example of this involved a car I owned which was in an accident. Thankfully, I was not a passenger, and no-one was hurt. I thought there was only minimal damage to the car – a dented front-end, and two released air bags. I was fairly confident the car could be repaired. To my surprise, I discovered it was cheaper for the insurance company to pay me the replacement value of the car rather than fix it.

Hockey was always running on borrowed time. The various tweaks and repairs did nothing to address the underlying problem: more money was being spent than generated. No business can operate indefinitely under such conditions: witness the recent JetsGo fiasco. When such a state exists, the company must be put out of its misery like a mortally-wounded animal. If may be resurrected, but only as a completely different company.

Macros Under a Microscope
This lesson applies on both a micro and macro level to documentation. One of the greatest struggles we face is updating existing projects. Sometimes you can get away with making specific changes, updates and tweaks. However, other times the original document is so outdated, and the changes so vast and so numerous, that it is not worth it to salvage it. You may have to rewrite an entire chapter, or even the entire manual. It can be easier to create something from scratch rather than trying to fixing something that is so thoroughly broken.

On a macro level, this principle applies to the entire information development process. As I’ve indicated in previous columns, we are experiencing a revolution in how documentation is created. We are reaching the limits of traditional documentation constructs: pages, chapters, books, and so on. These traditional “broken” systems are slowly being replaced by object-oriented documentation and content management systems. The effort required is incredibly expensive and time-consuming, but is the only long-term solution to effectively manage huge volumes of information that are overwhelming companies and information developers.

Lesson 4. Without compromise, nothing is possible. With compromise, anything is possible.
This is the final and most important lesson of all. Everything in the world that is created, including man-made objects, cities and countries, and even people (including you, dear reader) exists only as a result of compromise. Take the computer monitor you are staring at right now. At the company that manufactured it, there was probably one group that wanted it to be larger, another that wanted it smaller, another that wanted it to have more features, another that wanted less features. Every aspect of this monitor was debated, argued over and ultimately settled as a result of compromise. And as a result, you are now staring at this monitor. Don’t you just get a lump in your throat thinking about it?

Unfortunately, compromise seems to be the furthest thing from both sides in the hockey war. Yes, both sides did move quite a bit before the final breakdown, but it was too little too late, and neither side followed through. Since both sides appear unwilling to compromise, they should have agreed to binding arbitration, where an outside third party examines all the financial information, listens to arguments from both sides and then makes a decision. But agreeing to binding arbitration itself requires compromise, which was already in short supply.

Compromising Positions
Good documentation (like everything else) is built on compromise. No software or document ever released is perfect, complete and without error. It can always be made better, if customers don’t mind spending an infinite amount of money and waiting forever for it. At some point, development must stop, and the product and its documentation must be released, warts and all.

One of the more interesting meetings I have the privilege to attend are “bug reviews”. Myself, the project manager, the product manager, the developers, QA and others secretly gather in a locked, darkened room, lit only with candles, to discuss the current defects (or “bugs”) found in the application. We discuss each defect in turn, and often there is lively discussion about what to fix. Ultimately, the project and product manager decide the course of action to be taken:

1) Fix the defect.
2) Postpone the defect.
3) Document the defect.

All Hail the Documentation Emperor
That is, the managers decide which defect shall live and which shall die. It is all quite dramatic and reminiscent of the way, in ancient Rome, after one slave would battle another for sport, then the Emperor would give a “thumbs up” or “thumbs down” to indicate whether the losing slave should be killed or spared by the victor. Imagine how boring the death games would have been if a committee had been charged with making the final decision.

Ultimately, we must all become Documentation Emperors. We must fix what we can in the time allowed and compromise where necessary, but then must decide which documentation defect shall live, which shall die, and which can be postponed.

Compromise followed by solid action can save any documentation set, and will ultimately save hockey. If not, you can always watch curling!

Thanks to Bernard Aschwanden for the inspiration for this article.

Read More

Interviewing and Dating: A Single Source Solution

Last month, people celebrated "Valentine's Day", a day to celebrate romance and love, a day to be extra-nice to your partner, and a day that flower, card, chocolate and gift shops reap obscene profits.

As a tribute to this special day, this month's column will explore dating. Dating is so similar to job interviewing that we'll actually explore both of them simultaneously, using my one true love, conditional text, to distinguish each version.

Text that applies to interviewing is in blue; text that applies to dating is in, (what else?), red. Regular (black) text is unconditional and applies to both versions.

Playing The Interviewing Dating Game
Good interviewing dating skills are perhaps the most important skills you can have. After all, you will spend a significant amount of time at your job with your mate, so you want to be sure you make the right decision. Perhaps the only thing more important than interviewing dating is dating interviewing.

Both these activities are very similar: two people meet, often under stress, and try to size each other up within a relatively short time, in the hope of establishing a meaningful long-term relationship. One major difference is that at the end of an interview, date you probably won't end up naked working for that person.

Finding the right job person is not easy. You need to be well-connected. You need to establish a network of contacts who know you are "on the hunt". And you need to update your 1970's wardrobe. Disco is dead - get over it.

Sourcing Your Info

There are basically two sources of information you can tap into: public and private. Public sources include job hunting dating websites, services and advertisements. Note with public sources, you'll be competing against many other people, which why the success rate is often quite low. Therefore, don't spend too much time using these; instead, focus on the private sources of information.

Private sources include your various friends and contacts. Most potential "jobs" "mates" are not advertised. You need to tap into this hidden "job" "mate" market. The highest success rates are found by people who approach potential companies mates directly, or through a mutual contact.

Prep Time
Before an interview date, you want to be well-prepared. You should know yourself and be aware of your needs and wants. You should also try to find out as much as possible about the job other person as possible. What are their needs and wants? What are their problems? What do they value? What are they looking for in an employee mate?

Dress well before the interview date. Be appropriately groomed and styled. Allow yourself plenty of time to get to the location. If you are running late, drive as quickly as possible before any police can catch you.

Relax Already!
When you meet your interviewer date, be relaxed, cordial and friendly. Recognize that they are probably just as nervous as you are. Start with some small talk to break the ice, for example, the effect of the proton-to-electron mass ratio on the formation of the universe. Then you can move on to more complex topics.

It's always helpful if you discover something in common. For example, you may find that the other person worries if their documents clothes are up-to-date. Mention that you also worry about that and perhaps talk about ways that you've overcome this problem. It can make for great conversation.

Don't forget to maintain eye contact with the other person, to nod occasionally, and of course, to smile. These are all signs that you are listening carefully to what the other person is saying. Avoid drooling - it's not considered very professional romantic.

Listen Up
Don't dominate the conversation. The most successful interviews dates are ones in which both partners do about the same amount of talking. That's why it's important to listen as well as talk. Or as my crazy Uncle Fritz used to say: there's a reason God gave us one mouth and two ears. (Uncle Fritz himself had two mouths and one ear, but that's another story.)

Let the conversation flow freely and easily. Ask insightful and meaningful questions to find out more about the company other person. What are their biggest challenges? Where do they see the company themselves going? What makes the company them unique? Is that their real hair colour?

Ask And Ye Shall Receive
When you are asked questions, give simple, straight-forward answers. Don't ramble on, and don't forget to actually answer the other person's questions. Don't be a politician, who responds to questions, but doesn't answer them.

Be genuinely interested in the position other person, but not aggressive or desperate. You want to convey the message that you like the job other person, but that you don't need it them. One trick is to say that you have another interview date later that day. Be careful, though: jealously is a useful technique. Like weapons-grade plutonium, it has to be handled with care, otherwise it will explode and destroy your whole village. (Boy, I learned that the hard way.)

Faking Sincerity
It's very important to be yourself. There's no practical reason to pretend to be something you are not. If you do, you will end up stuck with a job someone that is not compatible for you. If you sense things aren't going well, and that's there's no "connection", be pleasant and polite, finish up the interview date as cordially as you can, but later let the other person know you're not really interested in the position a relationship. And no, throwing rocks through the other
person's office bedroom window is not considered a tactful way to terminate the relationship.

If you find you are genuinely interested in the job other person, you can start to "market" yourself. Casually tell them in a non-boasting way about your strengths. You don't want to appear boastful, but neither do you want to sell yourself short and be too modest.

Again, you need to strike the right balance. Don't lie about your exploits - you will be caught. Especially if you say that you single-handedly created single-sourcing the polio vaccine.

All's Well That Ends Well
You will know if the interview date is going well if the other person begins to loosen up a bit and starts talking about how you might "fit in" with them, especially with the staff their family. And if they start talking about benefits and salary kids and marriage, well then, you've really hit the jackpot.

Don't be afraid of rejection, and don't take it personally. If other person is not interested in you, it doesn't mean there's anything is wrong with you. It simply means that you and the other person just weren't a good "fit". Remember - there's plenty of other jobs people out there. Every rejection is simply one step to closer to finding the right job person. Just like every day is one step closer to the day you die. (OK, bad example, but you know what I mean.)

Thanks for the Memories
After the interview date is over, thank the other person for their time company, and follow up with an email phone call. (Showing up unannounced on their doorstep is not a good idea.) If you both think you want to move on to the next stage, you can arrange another interview date.

You can continue this until you both decide that you want a committed work relationship. At some point, you may be asked to sign a contract pre-nuptial agreement. Review this carefully, ideally with a lawyer. Note that the lawyer should not be the same person who interviewed dated you.

Breaking Up is Hard to Do
You may decide after some time, that the job is they are not really right for you, in which, you need to be honest with yourself and with your employee mate, and tell them it's not working out, and then go your separate ways. Always leave on good terms - you don't want to burn any bridges, because then you will be unable to cross the river of life.

This process repeats itself with other jobs mates, until you find the one you are looking for. And
when that happens, you will find true happiness, because you will have the job mate that helps you be the best you can be. (This is assuming you don't completely burn out first, in which case, you're screwed.)

A Perfect Ending
As you play the interviewing dating game, recognize that you are not perfect, and that your potential job partner is not perfect. The goal is to find one that is perfect for you. And if you can't find an employer mate who is "Mr. or Ms. Right", you can always opt for "Mr. or Ms. Right Now."

Best of success in your hunt!

Read More

Dr. Drake and the Information Equation

One of the most fascinating films of 1997 was Contact, starring Jodie Foster. Foster portrays Dr. Ellie Arroway, an astronomer who discovers a complex signal transmitted from another world. The signal contains a giant user manual describing how to build a machine that will magically transport a single occupant to another galaxy. The machine is massive and costs $500 billion to build.

The film explores the mad race to build the machine, the decision of who will ride in it, and what they will encounter, if they even survive the trip.
 
A SETI is Not a Couch
Although the film is pure science fiction, the organization to which Dr. Arroway's character belongs, the SETI Institute, is quite real. SETI, an abbreviation of "Search for Extraterrestrial Intelligence", is made up of scientists and researchers working to find intelligent life on other planets.

One of the real scientists working for SETI is Dr. Frank Drake. Drake is a leading American astronomer who in 1960, while working for the National Radio Astronomy Observatory, conducted the first radio search for extraterrestrial intelligence.

The Drake Equation
He developed a formula, called the Drake Equation, which tries to calculate the number of planets in our galaxy with beings who are intelligent enough to communicate with us.

The Drake Equation goes something like this:

N = R* x fp x ne x fl x fi x fc x L
which roughly translates in English to:
N = the number of civilizations within our galaxy that can communicate equals:
R* = the rate of formation of stars that are suitable for the development of intelligent life
x
fp = the fraction of these stars that have planets
x
ne = the fraction of these planets have an environment suitable for life
x
fl = the fraction of these planets on which life actually appears
x
fi = the fraction of these planets where intelligent life develops
x
fc = the fraction of these planets that develop communication
x
fl = the number of years that these planets exist

Based on this formula, Drake estimates there are about 10,000 planets within our galaxy that could communicate with us. Of course, the big question is, why haven't they?

There is no known solution to this equation, because is impossible to know what all these numbers are. However, this equation is still a useful tool for scientists. Although they disagree on the numbers, they mostly agree that the factors in this equation would be ones that determine what the final number (N) would be.

Don't Chain Me Down
This formula is a mathematical way of saying that a chain is only as strong as its weakest link. Because if any of these numbers are 0, there can be no possibility of us Earthlings finding someone else to talk to. That would be unfortunate, if you think of all the potential business opportunities for tech writers if we ever could produce documentation for other planets.
In our field, we don't seek other planets, but do seek to create the ultimate, perfectly complete and understandable document - this is our holy grail.

The Documentation Equation
Therefore, by applying the Drake Equation to information development, we can derive the Documentation Equation:
V = A x W x Aa x As x Tla x Tls x Tch x Tcl x Tc x Tr x Pa

In this formula, V is the Value of of an information set, or infoset, derived by multiplying the following values together:

1. A = infoset Awareness
   
2. W = Willingness to use infoset
   
3. Aa = infoset Access ability
   
4. As = infoset Access success
   
5. Tla = Topic location ability
   
6. Tls = Topic location success
   
7. Tc = Topic comprehension
   
8. Ut = User task completion
   
9. At = Application task completion
   
10. Tr = Task relevance
    
11. P = Practicality of application

Let's explore each of these values in turn.

V = Value of Infoset
This is the final value that we are after - a number on a scale of 0 to 100% that rates how valuable an infoset it is. An infoset is defined as any grouping of information or documentation, for example, a single document or a related set of documents, an online help system, a website, and so on.

Factors of V
V is derived by multiplying eleven factors together. The following sections describe each of the factors in this equation. The factors involve probabilities of what average users will do in an average information search situation. However, average user and average search situation are difficult things to define.

For the purposes of this formula, we'll just have to imagine that the factors describe what most users will be doing, or will encounter, most of the time, in most of the situations where they need information to help them complete a task or understand a concept.

1. A = infoset Awareness
This is the probability that the average user knows that the infoset they require exists. In most cases, this should be close to 100%, but sometimes users aren't even aware there is a manual or help system to refer to. If this is the case, the infoset has no value for that user. Fortunately, most users today have come to expect there will be some sort of information provided with their product, even though they may not always use it - silly users!

2. W = Willingness to use information set
This is the probability that the average user not only knows that the infoset exists, but is willing to use it. As we all know from experience, many users view documentation with the same affection as going to the dentist: it's a pain, but it's something you have to put up with once in a while. If a user does not want to use an infoset, it has no value.

3. Aa = infoset Access ability
This is the probability that the average user not only knows that an infoset exists and wants to use it, but knows where and how to access it. Sometimes a user won't know the exact location of an infoset. For example, they may not know where to locate a particular PDF file or support website that they need. Again, for these users, the infoset would have no value.
4. As = infoset Access success

This is the probability that the average user not only knows how to access the infoset, but is successfully able to do so. Examples of not being unable to access an infoset include trying to view a website that is down, or read a PDF or other type of document that has become corrupt and is unreadable.If a user cannot successfully access an infoset, it has no value.

5. Tla = Topic location ability
This is the probability that the average user is not only able to successfully access the infoset, but knows how to locate a specific topic. For example, the user would have to know how to use the "contents", "index" and "search" functions within an infoset to be able to even start looking for what they need. Inexperienced users may not have a clue where to start.If a user does not know how to locate a specific topic within an infoset, the set has little or no value.

6. Tls = Topic location success
This is the probability that the average user not only knows how to locate a topic in an infoset but successfully does so. This value will depend on the quality of the index, contents and search engine used in the infoset. It does not necessarily depend on the size of the infoset. Users should still be able to effectively search even the largest of infosets, provided the index, contents and search functions are well-developed. If a user cannot locate a specific topic within an infoset, the set has little or no value.

7. Tch = Topic comprehension
This is the probability that the average user can understand the specific topic they find. This factor is fairly straightforward: if a user can find the topic they were looking for but can't understand it, then the topic has no value to the user. This, in turn, lowers the value of the infoset.

8. Ut = User task completion
This is the probability that the average user can complete the task using the specific topic they found. For the purposes of this formula, there are two basic types of tasks:

• Procedural tasks: tasks that describe how to complete a specific procedure by following one or more steps.
  
• Learning tasks: tasks in which the user simply wants to know more about something but does not actually complete a procedure. Learning tasks include reading an overview, learning high level concepts, and understanding descriptions of terms used in the application.

In many cases, users are searching for procedural tasks. Whether a user can successfully complete a procedural task depends on the clarity and completeness of the steps listed in the task. If the steps are unclear or cannot be easily followed, the topic has no value.
A user can successfully complete a learning task if they can accurately understand the concept, idea or definition they were after. Again, this will depend on the accuracy and clarity of the topic.

9. At = Application task completion
This is the probability that the application itself will correctly complete the request task after receiving input from the user. This factor does not apply to learning tasks because these only involve understanding by the user, and not any application processing. Unless, of course, the user experiences the dreaded "brain malfunction".

This is similar to the previous factor but relates to what happens after a user successfully completes all the steps outlined in a procedural task. One would assume, at that point, that the application would take over and do whatever processing is required to complete the task. However, if there is a defect in the application, and the processing fails, then the topic becomes useless. Or to put it another way: the operation was a success, but the patient died.

The fact that this failure is not the information developer's fault is irrelevant. From the user's perspective, if they cannot complete the task, then the topic describing that task has no value.

10. Tr = Task relevance
This is the probability that the average user, after finding the topic they were looking for and successfully completing the task it contained, that the task itself was actually relevant to the user. That is, that it was the correct and appropriate task for what they were trying to do in the first place.

Now, you may argue that if the user has successfully found the topic they were looking for, wouldn't that automatically mean the topic is relevant to them? In most cases, yes, but sometime users will find the topic they want, but not what they need.

Microsoft Word - Stop the Insanity!
For example, someone may want to send out a letter to a group of people using Microsoft Word. A novice user, completely unaware of the mail merge feature in Word, assumes they will have to copy and paste the text of the letter several times, and then just change the name on each letter. As the letter changes over time, they assume they will need to do a "search and replace" of the specific text. They therefore search for and successfully find information about copying, pasting, searching and replacing. Instead, what they really needed was information about mail merging.

Now, the big question is: does the information they successfully obtained have value? This question is really a litmus test of what you believe the purpose of information development is:

Is it to give users the information they:
a) want?
or
b) may not know they want, but in fact, need?
If you believe (a), then you will always assign a value to task relevance of 100%.
If you believe (b), then you may assign a value to task relevance of less than 100%.

Neither choice is "right" but is something to be aware of as you try to determine the value of information.

One of the greatest challenges in information development is the fact that users don't know what they don't know. Great documentation is one that is able to anticipate users needs and clearly present them with information about how to do things in the most effective way possible, in ways that they may not have even anticipated. In other words, to read their minds!

11. P = Practicality of application

This is the probability that for the average user, the entire application is practical and relevant to them. This is similar to the previous factor, but deals with the application as a whole rather than the tasks that comprise it.

In most cases, we would hope this value would be close to 100%, but again users don't know what they don't know and sometimes work with the wrong tool. For example, a user could use WordPad to create basic documents. However, if they want to add elements such as borders, automatic page numbers, styles, tables, TOCs, indices, auto-numbering, and so on, they should use a full-featured word processor such as Word. Users who are using WordPad when they should a word processor may be doing what they want, but not what is best for their needs in the long run. They may find what they need to do in the WordPad help, but the help has little value if they are using the wrong tool.

Again, it comes down to whether you believe information should only give users what they want, even if what they want is not the right thing. It is the ultimate catch-22: if we try to give users what they need, we are called arrogant, self-righteous, know-it-alls. If we try to give users what they want, we are called weak, unhelpful panderers who are too lazy to tell users what they really need to know. Select whichever insult bothers you less and run with it.

The V Files - "The Truth is out There"
By multiplying all these factors together, we obtain V - the value of the infoset. The highest possible value for V is 100%, which although theoretically possible, is in practice, impossible. This is because there are too many uncontrollable variables, not the least of which are the users themselves. It is impossible to predict if or how every user will try to search for information, if they will find and understand the information, if they will successfully complete the task, and so on.

In fact, because V is derived by multiplying eleven numbers together (rather than adding them), the value of V will usually be very small. For example, if an infoset scored 90% in every variable, the value of V would be .90¹¹ or a measly 31%. Even if the infoset scored a whopping 97% for every value, V would be just 71%.

Therefore, V, by itself, is a meaningless value. A score of 31% simply indicates that the particular infoset has a value of 31% of what is theoretically perfect. To give meaning to this value, you'd have to compare it to all other appropriate infosets. So, for example, if similar infosets for similar products scored an average of 23%, and the infoset you developed scored 31%, yours would be considered "above average". The challenge is to define what are similar enough infosets to the one you are rating that you are making a meaningful comparison. That is, you want to compares apples to apples, and not apples to coffee mugs.

Summing Up the Numbers


The Drake Equation and the Information Equation have much in common.

In both, it is impossible to obtain completely accurate numbers for all the values. You may be able to get some of the values if you were to spent huge amounts of money on research, however then you would have to justify your return on investment.

Therefore, for both equations, the purpose is not necessarily to find the true numbers, but rather to make people aware of the factors that lead to the final value.

Your assignment, therefore, should you choose to accept it, is to find other factors that could be incorporated into the Information Equation. In doing so, you will help solve one of the greatest mysteries of our time:

What makes information have value?

Read More

Clear Eye for the Documentation Guy

Let's start the new year with a tribute to every metrosexual's favourite show, Queer Eye for the Straight Guy.

Clear Eye for the Documentation Guy


Introducing the "Clear Eye for the Documentation Guy" team:

• Carson - Customer Review
• Ted - Information Development
• Jai - Content Management
• Thom - Information Design
• Kyan - Indexing & TOC

* * *
Meeting the Guys

Carson: OK - so who's our first documentation victim?
Ted: His name's Lionel. He's a tech writer from New Jersey, and he works at a place called "Fabulous Systems"
Carson: Oooh - great name. I think I'll call my first-born child that.
Ted: Unfortunately, things aren't so "fabulous" for Lionel - he's been working on a big user guide; it's over 300 pages long. It's for the company's flagship product, "The Web Whacker", which is, according to the company's website, the "premier tool for safely removing spyware and cookies from your system".
Carson: But why would you want to get rid of cookies? Cookies are yummy-licious!
Thom: I guess if you want to retain your girlish figure.
Ted: Anyway, Lionel needs help. The user guide and online help need alot of work. Currently, Lionel's using a separate tool for each.
Jai: Two separate tools? Oh my god!!
Ted: Yeah, his documentation is really hurting. Seems it hasn't been reviewed since the middle ages. There's broken cross-references, outdated screenshots, missing procedures, wrong info, duplicate text...
Carson: Oh stop it! You're killing me alot!!
Thom: We gotta help this poor boy make his docs shiny and new. He needs the "clear eye" treatment right away...
Chorus:

You came into my life
And my docs never looked so bright
It's true, you bring out the best in them
When you are around
When you are around
My docs just keep getting better

The reviews keep getting better
Drafts keep getting better
All the content just keeps getting better...

Abusing the User Guide
Carson: OK - here we go! Let's get that boy's docs "straightened" up!
Lionel: Hey, it's the fab doc five! What's up?
Carson: The quality of your documentation, once we're done ravaging it. Let's see your little monster of a user guide...
(Everyone gets a copy of the guide to gawk at.)
Thom: Oh my god - what's that smudge on the cover?
Lionel: Uh, that's our company's logo. The resolution isn't so hot.
Carson: "Isn't so hot"? Honey, it's colder than Martha Stewart at the North Pole.
Jai: What's up with the table of contents? It's 17 pages long!
Carson: I guess he likes a big table. You can seat more guests that way...very festive.
Lionel: Yeah, it is kind of big, I guess. It has all the headings up to heading level 5. I couldn't really figure out how to make it shorter.
Carson: Some things are better longer, trust me.
Jai: Don't listen to him - he's evil. We're gonna make your TOC R-O-C-K!
Thom: Uh, excuse me - why is the word "actualize" in your document?
Lionel: I think that came from marketing.
Jai: I don't think that's really a word, is it?
Carson: It is on one of Jupiter's moons, "Psycho".
Kyan: We need to send that word back to the depths of hell from which it came.
Ted: Uh oh - you've got a cross-reference here that points to a page that doesn't exist.
Carson: Oh, it exists, alright - you just need to wear your special super-duper magic wizard x-ray glasses to see it. Either that or drink lots of champagne and say the magic incantation: "there's no page like home... there's no page like home..."
Thom: Hey, I can't see what's in this screen shot on page 246. The type in it is tiny!
Jai: Maybe your eyes are too big.
Carson: Oy vey - where's an electronic microscope when you need one?
Ted: It's OK - I brought a magnifying glass just for this occasion. Let me take a look. OK - I think can make out the letters - wait a minute - I think it's in hieroglyphics.
Carson: Boy, those ancient Egyptians really knew how to make software, didn't they?
Lionel: I think some of the fonts in the screenshots got "pixilated".
Thom: Those pixies will get you every time.
Carson: We'll just sprinkle some magic anti-pixie dust on the screenshots - that should fix it.
Thom: Uh - you've got a procedure here with 32 steps. Don't you think you should break it up a little?
Carson: Don't you know that breaking up is oh-so-hard to do?
Jai: Hmmm...your index is interesting. You have entries for "edit", "change, "modify" and "update".
Carson: Well, at least he's consistent.
Jai: You've also got some entries in uppercase, some in lowercase and others in mixed case.
Ted: Oooh - I'm not comfortable with "mixed case". We don't want those capital letters fraternizing with those lowercase letters. Who knows where that could lead?
Thom: I wouldn't make a federal "case" out of it.
Carson: But it's definitely a "capital" offense. He's probably all mixed up from having to sort out his multiple personalities.
Thom: Lionel, when was the last time someone actually reviewed this guide?
Lionel: Hmmm..I'm not really sure...
Carson: Maybe all the SMES got sucked up into that 24-hour black hole that's been floating around. You know, the SME-sucker.
Lionel: It's probably been awhile.
Jai: A while? How long is a "while"?
Ted: I think the going exchange rate is two "whiles" to a year.
Carson: Save the "whiles", I always say...you never know when you might need one.
Thom: OK - I think we know what needs to be done. And we're just the guys to do it!
Carson: That's right! It's a group effort! Remember, people, there's no "I" in "technical writing"!
Thom: Let's get to work...
A Long "While" Later...
Ted: OK, Lionel. We're done with your documentation makeover. We're going to take you through what we did.
Carson: And be sure to take notes, you bad boy. There's a test later.
Jai: A test? Written or oral?
Ted: Don't go there...We'll start with Carson, our Customer Review guy...

Carson's Catchy Customer Review
Carson: Well children, as we all know, the first step in any makeover is to look at what you've got, then work the problem. Like I always say: "if you're not part of the solution, you're part of the equation."
Thom: Uh, Carson, shouldn't that last part be "you're part of the problem"?
Carson: No, you're part of the problem! Anyway, I took out a bunch of your customers for some lovely Japanese tea, and I picked their cute little brains about the documentation. I'd tell you what they said, but I'd be breaking about 14 FCC obscenity regulations. Let's just say there's definitely been a major "documentation malfunction".
The gist of it is, the users weren't very happy campers. They couldn't find what they were looking for, the index was like a bad hair day, tons of your procedures didn't have any of those darling "big picture" overviews, and half your users of them are now legally blind from trying to read your Egyptian screenshots.
Lionel, your user guide and online help were really "criminal", but the fab doc five have joined forces to expunge your record, so you no longer have to live in fear in the technical writing witness protection program.
Ted, our Information Developer, will be the first one up to tell you how we healed your very sick docs...He is truly the Doc Doctor.

Ted Takes A Turn
Ted: The big problem was that you had the manual organized by product modules, rather than by task. So we restructured things to be more task-oriented. This includes always having an action verb in your headings.
Thom: Ooh - where I can get some action?
Ted: So, for example, instead of headings like "Cookies" and "Pop-Up Ads", we now have "Deleting Cookies from Your System" and "Getting Rid of Pop-Up Ads".
Another big problem was that many of the procedures were out of date, inaccurate or just plain missing. We sat down with the developers and went through every screen, field and process in the application, and cross-checked it against the document. We found some real information "jewels" that were missing.
Carson: Gotta take care of those family jewels, people!
Ted: We talked to your very friendly QA and support gangs and asked what were the most common problems and the best way to fix them, and then we stuck that info in the guide. That should help your support people, who I think were on the verge of a nervous breakdown.
We updated all your screen shots, fixed all the broken cross-references, broke up procedures that were too long, added a bunch of missing overviews, and, as a special treat, we added another chapter - if you turn to page 426...
Thom: Wow - a Glossary of Terms!
Carson: Hey, let's look up the meaning of life.
Ted: We also got rid of a lot of your duplicate text. I'm going to turn it over to Jai, our Content Management God, to talk about that.

Jai, the Content Management Master
Jai: For some wacky reason, you were using one tool to develop the Online Help and another for PDF file, with practically the same content in both. That's a big no-no.
Carson: It's actually a no-no-no-no-NO!
Jai: We went through and merged all the text together into one document, which you can output as a PDF or a Help project - whatever your little heart desires. This should cut your workload in half.
Carson: This means you only have to work 2 1/2 days a week. Your boss will be ecstatic!
Jai: We also noticed you had two different product versions: a regular edition and a professional edition. In your guide, you had stuff like "If you are using the regular edition...". or "If you are using the professional edition" with almost the same procedures in each part. That's another no-no.
Carson: I think we're up to about 6 no's, no?
Jai: We merged the duplicate procedures and used conditional text for each version. Now, the regular users will only see the stuff that applies to them; same goes for the "pro" users.
Carson: "Regular"..."Pro"...can't we all just get along?
Jai: Up to this point, we've only been talking about the content. Thom, our Information Designer, is going to give you lowdown of the "look and feel".
Carson: I wouldn't mind doing a little "looking and feeling" myself...

Thom the TOC Terminator
Thom: OK. Basically, your choice of fonts was more messed up than Robert Downey Jr.
Ted: Hey, don't make fun of Robert - he's misunderstood!
Thom: You used three different fonts in your headings and the point sizes ranged from 10 to 30.
Jai: Oh my god! Lionel - what colour is the sky in your world?!
Thom: We fixed things so that your Heading 1 is now a very respectable 16 points, followed by 14 points and 12 points for Headings 2 and 3. And all your headings now use the same font.
In your online help, you were using serif fonts, which are harder to read on-screen than sans serif fonts like Arial.
Carson: Serif fonts on screen?! Gag me with a CD-ROM!
Thom: All your help fonts are now sans serif. The help files have a clean and simple look, with three tabs: Contents, Index and Search. We've also got your standard government-issued help buttons for navigating, bookmarking, printing...
Carson:...eating, drinking, shopping, bitching...you get the idea...
Ted: It should all go very nice with your furniture.
Thom: In the long run, we're recommending that you get a content management system. You've got lots of stuff that repeats throughout all your documents. A content management system, or "CMS", will get rid of the duplication, and help you build and maintain documents much more easily.
Carson: So you need to get an XML CMS ASAP, and you'll be a VIP and maybe the next VP, or else you'll be MIA.
Jai: Let's not push the boy too hard. I think he's still in shock from what we've done so far.
Carson: But we're the "shock and awe" gang. I love that phrase - "shock and awe". Reminds me of "Chaka Khan", that cute little one-hit wonder.
Ted: Kyan is going to wrap things up by explaining how we handled the front end and back end of your docs - your TOC and index.

Kyan the Kleaner
Kyan: As we talked about earlier, your TOC, at 17 pages, was a "tad" unwieldy. People need a TOC they can quickly scan. It shouldn't try to be an index.
Carson: Yeah - that's like Madonna trying to be an actress. Or a singer...
Kyan: Your TOC now has just the chapter titles and headings 1 and 2. This knocks it down to 5 pages, a much more digestible amount.
Thom: And we all know how important it is to have good digestion.
Kyan: Moving on to your index. Well - what I can I say? It was scarier than the documents that programmers try to write.
Carson: Oooh, that is scary! I'm so scared I want to put on my witch's hat.
Ted: Which witch?
Kyan: Oh stop it!
In your index, you had entries jumping to the wrong location, your case was all over the place, you had a bunch of different words describing the same thing, and many of your topics had no entries.
Thom: Lionel! Kyan! For shame! Shoot zem. Shoot zem both.
Kyan: We went through all your index entries, cleaned them up, took out the dead ones, added a bunch of live ones, and made everything groovily consistent.
Carson: Basically, we made it look like Sybil didn't write it.
Ted: So there you have it, Lionel - we took your user guide from junky to funky! How do you feel?

The Fab Four Win Again
Lionel: Wow - I'm speechless. You guys are the best. I don't know what to say. You saved my life!
Carson: Oh stop it, I'm getting all teary-eyed.
Thom: Someone throw that man a hanky.
Ted: Wow - yet another document restored to sanity. We did good, fellahs!
Jai: This should really impress his boss - he'll probably get a promotion.
Carson: Yup - he could be the next CFB: Chief Font Boy.
Kyan: Sounds good. A toast - to Lionel - may his writing never falter, may his screenshots be sharp and pure, and may his hard drive never fail.
Carson: And may he always remember our motto:
Carson, Ted, Jai, Thom and Kyan (in unison): We're here, we're clear, get used to it!

Read More