Krazy Karl Rabeder

Related imageKarl Rabeder is an Austrian millionaire. Or at least he was. He’s giving away his entire $5 million fortune to charity.

“My idea is to have nothing left. Absolutely nothing,” he said. “Money is counterproductive –it prevents happiness.”

Karl continues: “For a long time I believed that more wealth and luxury automatically meant more happiness,” he said. “I come from a very poor family where the rules were to work more to achieve more material things, and I applied this for many years.”

Later in life, his views changed. “More and more I heard the words, ‘Stop what you are doing now — all this luxury and consumerism — and start your real life’,” he said. “I had the feeling I was working as a slave for things that I did not wish for or need…I was just listening to the voice of my heart and soul.”

So, he has moved out of his mansion into a small hut. I wonder Mrs. Rabeder thinks of her new home.

If Karl’s move is successful, he should write a user guide describing the process: The Millionaire’s Guide to Living Poor. It could cover such topics as:

  • Filth is Your Friend
  • How To Eat Almost Anything
  • Got Mud and Straw? Let’s Start Building A Home!
  • Saying Goodbye to Your 55″ TV
  • Convincing Your Family that Poverty Builds Character (yeah, right)

I sympathize with Karl. Feeling sad sometimes is completely normal. I’m just not sure the solution is to become a hobo.

We’re often challenged by our docs. A draft review comes back, and it ain’t pretty. That doesn’t mean we have failed; on the contrary. The only thing worse than a draft full of revisions is a draft with none. Mistakes and omissions are important; from them we grow into better technical communicators.

It’s also important to remember that the end user never sees all the changes, heated discussions, endless debates and other nonsense that occurs when a document is being developed. All they see is the final product. They don’t know, nor do they care, about how it got there, just that it’s good now.

Think about it – do you care about all the errors that were made before you got your hands on a product you were using? Whether it’s a TV, a chair or a pair of shoes, all you care about is that the errors were resolved. Especially if you own a Toyota.

So, if work’s getting you down, don’t quit, and don’t move into a hut. Savour the challenges. For when you hammer steel, it becomes harder.

We’re here, we’re synesthesic, get used to it

Image result for synesthesiaSynesthesia is the ultimate mashup. It’s a neurological condition in which a person experiences the data of one sense with another – a sort of warped virtual reality.

Examples of synesthesia are:

  • seeing numbers and letters as colours: for example, where most people see the following text as black: ABC 123, a synesthesic might see it as: ABC 123
  • perceiving numbers, letters, days of the week and months as emotions or personalities: for example: 1 as “strong”, H as “envious”, Tuesday as “sad” and July as “jealous”
  • seeing sounds: a loud noise such as dog barking or fireworks exploding might cause the person to see certain shapes or patterns
  • perceiving time periods as locations in space: for example: Monday appears “further away” than Wednesday
  • “tasting” certain words or letters: for example, most tastes like toast, and leg tastes like egg

Scientists aren’t fully sure what causes synthesia, but agree it’s probably some sort of neurological malfunction in which the sensory wires in the brain get crossed. It may affect as many as one in 23 people.

Blessing or Curse?

At first glance, synthesia might seem like a curse. After all, who would want the distraction of “hearing” colours or “seeing” sounds? In fact, it may be a blessing. Some synthesics are very creative and have produced unique drawings and other artwork that illustrate the remarkable way they experience the world.

Synthesia, Tech Comm Style

An effective technical communicator is partially synesthetic. We simply would not be able to do our jobs well if we perceived information the same way normal people do.

Specifically, technical communicators are hyper-sensitive to vague, missing, misspelled, confusing, incomplete and poorly organized information. We perceive it as jarring, illogical, uncomfortable and painful. We can call this condition technical communication synthesia, or TCS.

TCS Examples

The following examples help illustrate TCS. In each one, you’ll see three statements:

  • Actual text – the actual text that might appear in a document or software application
  • Normal perceptionhow a normal (non-TCS) person perceives the text
  • TCS perceptionhow a person with TCS perceives the text
  • Actual text The record is updated.
  • Normal perceptionGreat! The record is updated. My work is done!
  • TCS perception The record is updated?! Who or what updated the record? The user or the computer? The objective voice is evil.
  • Actual text Welcom too the Synex Usser Giude .
  • Normal perceptionHmm, something doesn’t quite smell right…
  • TCS perception The horror; the horror…
  • Actual text The Sort command sorts your data.
  • Normal perceptionGee, who would have thought it did that?
  • TCS perceptionCircular references are evil! Change this to: Use the Sort command to arrange your data alphabetically or numerically.
  • Actual textThe program will remember your settings.
  • Normal perceptionAwesome! I can just set it and forget it!
  • TCS perceptionRemember? How can program remember?! Anthromorphization is evil!
  • Actual textError 43 – Incompatible file format.
  • Normal perceptionDamn! Where’s the tech support number?!
  • TCS perceptionWhere is the problem? What is the solution? And who cares what the error number is?
  • Actual textAbort the process.
  • Normal perceptionYikes! I’d better stop the process.
  • TCS perceptionAbort is a word more loaded than an H-bomb. Change to: Stop the process.
  • Actual textIt’s important to back up your files.
  • Normal perception – That’s nice to know….uh, what’s a “back-up”?
  • TCS perception – What is a back up? Why is it important? How do you perform one? Which files do you back up? How often should you perform one?
  • Actual textDo you want to enter more records? [OK] [Cancel]
  • Normal perception – Yes, I do, so I’d better click OK .
  • TCS perception – Ouch! Why can’t developers label buttons properly?! Change the buttons to a simple [Yes] and [No].
  • Actual textTurn off your computer. Be sure you have saved your work first.
  • Normal perceptionOK, I’ve turned off my computer Now what? Make sure I’ve saved my work first?! Doh!
  • TCS perceptionMight as well say: Cut the red wire to detonate the bomb. Change to: Save your work, then turn off your computer.
  • Actual textTo print a document, make sure you have opened the document you want to print, the printer is on, there is paper in the paper tray, and that the printer has enough ink, then press Print and select the correct printer, paper size, orientation, the pages you want to print and the number of copies, then click OK.
  • Normal perceptionYou had me at “To print“. Then you lost me. I am sad.
  • TCS perceptionCould that sentence be any longer? Rewrite to:
To print a document:
  1. Ensure the printer is on.
  2. Check that there is paper in the paper tray.
  3. Check the ink level of the printer.
  4. Open the document you want to print.
  5. Click the Print button.
  6. Select the paper size and orientation.
  7. Select the pages you want to print and the number of copies.
  8. Click OK to print.

Note: TCS is incurable, thankfully.

Synecdoche, Technical Writer

Image result for Synecdoche, New YorkThink being a tech writer is difficult? Try being a screenwriter. Unlike technical writers, most screenwriters will never make a successful living. Most of them work other jobs to pay the bills. The vast majority of scripts never get produced. As with actors, dancers, musicians, and other arts professionals, most screenwriters are doomed to a life of obscurity. But there is one screenwriter who is not only widely successful, but is one of the most talented and original writers in modern times.

Charlie Kaufman is the writer and director of the film Synecdoche, New York, and was also the writer on two of my favourite films: Eternal Sunshine of the Spotless Mind and Being John Malkovich. These movies wonderfully use the medium of film to explore the very nature of reality and existence.

You Are My Sunshine

In Eternal Sunshine of the Spotless Mind, Joel Barrish, heartbroken over the breakup with his girlfriend, undergoes a procedure to erase all memories of her. (His girlfriend had previously erased all memories of him.) As Joel is sleeping, we see his memories become mangled and eventually destroyed. It is the closest thing you’ll see to the filming of a dream.

In the other film, Being John Malkovich, John Cusack plays a puppeteer who takes a menial office job in an unusual building – the work floor is wedged between two others. Behind one of the office walls, he discovers a tunnel that is a magical portal into the mind of actor John Malkovitch. A portal visit lasts about 15 minutes, after which the visitor is spewed out onto a filthy ditch near the New Jersey turnpike.

Synecdoche: The Whole and its Parts

In Synecdoche, New York, which I have not yet seen, Kaufman makes his directorial debut, in addition to being the writer. The plot involves a struggling theatre director who stages an extraordinary play by creating an intricate replica of New York City inside a gigantic warehouse. He hires actors to play himself and the other people in his life. These actors interact with their real-life counterparts, blurring the line between the director’s real and “staged” lives.

Life, Defined

Kaufman’s films are fascinating because they artistically document the questions all users (in this case, all people) have, including:

  • What does it mean to exist?
  • What is life? Is it just a collection of memories?
  • Do we really have free will, or are we simply actors following a script?
  • What is perceived? What is real? Is there a difference?

Model Documents

Like screenwriters, technical communicators also model reality.

First, we create guides that describe how to use something. We model our guides directly on the thing (the reality) that we are documenting.

Second, by modeling our documents this way, we are creating a model of a tutor or teacher. This can be vividly seen in interactive online training, which responds to and progresses based on the choices the student makes in the course.

Reality – What a Concept

However, there is a third, deeper level that some documentation can follow as it models reality. Just as Kaufman’s films blur the line between the real and the perceived, certain documentation blurs the line between the documentation and the object being documented.

The simplest example of this is a hyperlink. Before there were hyperlinks, when you needed to refer the reader to another source, you gave the name of the source and page number, for example: see page one of The New York Times. Then the hapless reader actually had to go out and find the damn document. Now you can simply say: click here. See the difference? The text of the step is the same as the step itself.

Virtual Control

A more complex example can be found in other software. For example, in the Windows online help, there is a topic that describes the Control Panel and how to open it. But it also contains a link that when clicked, actually opens the Control Panel. Now the question becomes: is this link documenting the Control Panel or is it actually the Control Panel?

We can go even further and ask: what exactly is the difference between the reality of the Control Panel, indeed, of all software, and the reality of the online documentation that describes it? They all exist only within the computer. Is one more “real” than the other? If you were to show both to someone who had never seen or heard of computers, they would be unable to tell the difference. Ultimately, they are all electromagnetic charges on a spinning metallic platter.

In essence, we are objectifying the Control Panel, our Windows files and folders, the various icons, and other elements of the operating system. How is this any different than objectifying people?

Synecdoche, North York

If Charlie Kaufman were ever to write a movie about a technical writer, the plot would be as follows:

Jacob is a struggling technical writer. He has trouble finding and keeping jobs, because he just does not fit in. He also struggles to relate to other people, finding that they are not as easy to follow as the documentation he writes.

In an attempt to gain control of his life, he begins to document every aspect of it. At first, he writes only on the computer, but these documents are too “soft” for him – he needs something real. He begins printing out everything he writes.

Soon, his entire apartment is awash in papers. The walls, furniture, floors, even his dog are drowning in an ever-growing sea of documents. In a dream sequence, Jacob imagines the entire world covered with explanatory notes.

In a vain effort to regain control of his mind, Jacob begins scouring the Internet for answers. In his search, he stumbles upon a blog written by a technical writer living in the former city of North York. To his amazement, he finds an article written about him, when he

__________________________________________________

Blogger Error – someone has accessed your account
__________________________________________________


Hey – Andrew. Just what the hell are you doing?

Excuse me? Who are you?

I’m Jacob, you idiot. Where do you get off writing about me like that?

Well, it’s my blog. I can write what I want.

No, you can’t. You make me sound useless and pathetic. Knock it off or I’ll come down there and kick your ass!

Well, that would be a neat trick. You know – you only exist because of me.

Actually, Andrew, the opposite is true. I mean, can you prove that you are not a figment of my imagination?

Uh, OK. I think I’ll stop writing now.

Oh please, don’t stop. You can’t imagine the darkness when you stop. I’m sorry…

I can’t just keep typing forever. I have a life, you know!

I have a life too! Please, I’m begging you! Keep typing!

Nope – I’m stopping now.

You wouldn’t dare. You need me! Without me you’re nothing! Your stupid blog is nothing! You’re going to keep typing until


**************************************
Unauthorized access terminated
**************************************

A Killer Manual

Image result for Hit Man: A Technical Manual for Independent Contractors.The FBI, while investigating American Nazi Bill White for uttering death threats, found a guide in White’s apartment entitled: Hit Man: A Technical Manual for Independent Contractors. Hey, even Nazis need technical writers.

Here’s an excerpt from this manual:

Within the pages of this book you will learn one of the most successful methods of operation used by an independent contractor. Step by step you will be taken from research to equipment selection to job preparation to successful job completion.

This paragraph, of course, raises some obvious moral questions, such as: should the phrase step by step be written as step-by-step?

Similar instructions appear on White’s website, including a topic entitled Kill Richard Warman, which states:

Warman should be drug out into the street and shot..[he] is an enemy, not just of the white race, but of all humanity and must be killed. Find him at home and let him know you agree.

Based on this excerpt, it is doubtful anyone would hire Mr. White to be on their tech writing team. First, “drug” should be “dragged”, but more importantly, this procedure does not describe exactly how to drag Warman out, an unforgivable oversight.

I would not recommend Mr. White include this excerpt or technical guide in his portfolio. It would be bound to raise an eyebrow or two.

Taking Stock of Stocks and Docs

Related imageIt sure has been a memorable last few weeks for the world’s finances. Stock markets worldwide have tanked, and there is talk of a worldwide recession. The whole messed is linked to something called sub-prime mortgages, which really should have been called sub-par mortgages, or better still stinky rotten loans – further proof that terminology is everything.

This whole fiasco has become a litmus test of whether you believe in free will. Many believe the government or the financial institutions who either encouraged or pushed these ridiculous high-risk loans are to blame, because they foisted these loans on unsuspecting, gullible people. Others believe that the people who took on these loans knowing that they really could not afford them are to blame. If you believe the latter, you are a free will advocate. It reminds me of an actual sign I saw for a lawyer’s service: Free Will Review.

Responsibility is everything. When a document is released with incorrect or missing information, who is to blame? The reviewers, including the product manger, business analyst, programmers and QA? Or the technical writer? Who is ultimately responsible? Is everyone responsible?

There are tech writers and then there are great tech writers. The more senior you are, the more responsible you must be. Even when others may share in the blame, you need to have the courage to say: I own this document, so ultimately I am responsible. Now let’s fix it, and move on.

The Incomplete Guide to Gödel

Related imageKurt Gödel was an Austrian-American mathematician who lived from 1906 to 1978. He’s best known for his incompleteness theorems, which have had a tremendous impact not only on mathematics but on other sciences and even philosophy.

Gödel’s theorems were actually a response to the ideas of another mathematician, David Hilbert. Hilbert had a dream of creating a complete, accurate and consistent system for all the mathematical principles (or axioms) that had been discovered to date. Earlier, some of these axioms were discovered to be wrong, so there was tremendous pressure to ensure such errors would never occur again. Hilbert wanted to establish a solid foundation for all mathematics, now and forever.

Sounds like a great idea right? There was just one problem – to create such a “perfect” system is impossible, and Gödel proved it. He demonstrated that if you created a complete system that described every mathematical truth, it would contain some statements that could not be proven. In other words, the system would be complete but not fully predictable or accurate. Conversely, you could create a system that is fully provable, but then it would not be complete.

How Gödel did this is incredibly complex, but I will try to explain. He essentially created a mathematical system using a complex numerical notation, where one of the statements in the system was: This statement cannot be proven.

Now, if this statement could not be proven, then the system might be complete, but it would contain a non-provable statement, making the system itself inconsistent. But, if the statement is provable, then it means the system still contains a non-provable statement (because the statement itself says it can’t be proven) and therefore the system itself is still not fully provable.

As a workaround, we could just leave this pesky statement out of the system, because it’s causing so many problems. However, if we do that, then the system would be missing a statement, making the system fully provable, but incomplete.

To summarize, Gödel was saying that any system can be:

  • complete but not fully provable
    or
  • fully provable but incomplete

This was Gödel’s first incompleteness theorem. His second theorem went further and said that any system can never be complete. That is, any system containing true statements will always be missing some statements, but you can never know what they are. (If you did, then they wouldn’t be missing, would they?)

The philosophical impact of Gödel’s theories are enormous. Extrapolating his ideas, it means that we can never know everything, and that even if we could, some of what we know could never be proven.

The implications for information developers should be clear. All documents are essentially collections of statements, namely theory and procedures. It is impossible to create a document that is complete, and we don’t even need Gödel to show this. Users are complex beings and therefore completely unpredictable. Compounding this is the fact that the product being documented (especially if it’s software) is also unpredictable. Mathematically, we would express these two facts as:

user unpredictably x product unpredictably = lots and lots of unpredictably

It is therefore impossible to create a complete guide that would explain every possible situation. Even if you could, it would contain statements that are not true. Again, we don’t need Gödel to prove this. Too often we see guides that try to be complete, and in doing so sacrifice quality and accuracy. That’s why the mantra of every tech writer when responding to pressure to quickly complete the draft should be: “Do you want it fast or do you want it right?”

More importantly, if you really did try to create a complete guide, it would have a size approaching infinity, which is a rather large number. Some of the best examples of documentation are quick start guides, usually just a few pages, or as a fold-out poster. Size does matter, but not in the usual way, because less is often much, much more.

This column is now complete, but of course I cannot prove a word of it.

Tech Writer, Illusionist

Illusions are endlessly fascinating. We love to be fooled, but why?

I think it’s because deep down, illusions don’t simply mystify us, but inspire us. An illusion represents a conflict; a contradiction. It not only suggests that the same thing may be true or false, but, more importantly, that it can be both of true and false at the same time.

Look at this classic drawing “Waterfall”, by the Dutch artist M.C. Escher:

Is the water flowing up or flowing down? It appears to be doing both at once.
I had trouble building this ever-ascending staircase in my house:

This guy was trying to straighten out the Tower of Pisa – too bad he was kicking the wrong side:

I’d love to see the tools that made this lovely ring sculpture. I could probably make one of these myself, if I find some hyperbolic space lying around:

Don’t worry – it’s safe to swim in this pool. The creatures are part of the pool’s floor tile pattern. Yes, really.

Here’s a photo of some construction workers at a nearby park. They’re very handy guys because they can work in up to 11 dimensions:


Either these wheels or my head are spinning:

Wow – I didn’t know they could breed horses so small. Must be that new-fangled generic engineering we keep hearing about:

Illusions are paradoxes, as is information development itself. Look at what a technical writer has to do:

  • make the technical non-technical
  • make the complex simple
  • construct one guide for many different users
  • present information at many different levels simultaneously
  • in software, tell users to perform physical tasks (click, move and manipulate) on non-physical objects

This last point is a key point. What exactly are we saying to users when we tell them to “Click the OK button”. There is no button, but only a visual representation of one. They do not actually “click” the button. They move an external pointing device, which in turn moves a cursor in a somewhat corresponding way on a screen, then they position this cursor over a virtual button and click, not a button on the screen, but the button on the mouse.

Lest you think I’m being picky, try explaining how to use a computer to someone who has never seen one. It is a damn near impossible task. I actually remember the first time seeing someone use a computer. They had tremendous difficulty manipulating the mouse. We take it for granted, forgetting that we too had a steep learning curve.

We often become frustrated with our users and say (or want to say) things like:

  • Why can’t you understand this? It’s so simple!
  • You’ll see it – you just have to try harder.
  • I don’t think you’re really trying to understand.
  • You just don’t get it, do you?

MindFreak
All of the illusions presented so far are interesting, but none are anywhere near compelling as the final one I will share with you. It is, quite simply, the best illusion I have ever seen, because it pushes the very limits of reality and perception.
Look closely at this checker board:

You see a dark square marked A and a lighter square marked B. Except there’s just one little detail:
A and B are the same colour.

I’ll say it again in case you didn’t quite catch that: A and B are the same colour.

(It’s situations like these that the word “flabbergasted” was invented.)

I know what your thinking: “A is obviously darker than B. Come on! Are you (colour) blind?!”
I agree – A and B do appear to be different colours, but they are the same, and here is the proof:

So, now that you know that the two squares are the same colour, take another look at the illusion, concentrate really hard and you should now see that the two squares are indeed the same colour:


What? You still see them as two different colours? But I just proved to you they are the same colour!

At this point, I have to tell you:

  • Why can’t you understand this? It’s so simple!
  • You’ll see it – you just have to try harder.
  • I don’t think you’re really trying to understand.
  • You just don’t get it, do you?

Reality – What a Concept

An illusion like this makes the following mathematical statements:

Statement 1: A > B
Statement 2: A < B
Statement 3: Both statement 1 and statement 2 are true.

This, of course, is impossible, and that is exactly what this illusion, indeed, all illusions are saying, that the impossible is quite real. If visual impossibilities can exist, then how much more so can informational impossibilities and paradoxes exist, for pure information is much less tangible and more ethereal than anything visual.

Being a technical writer means being the ultimate illusionist. We make the intangible tangible, the complex simple and the impossible possible. We pick the rabbit out of the hat while everybody sits out there wondering how the hell we did it.

Technical Writing and the Art of Haiku

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

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

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

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

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

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

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

Poetry in Motion

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

Here is a modern example:

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

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

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

And now, on to the poetry…

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

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

“Let’s take it offline”
the manager sings
We are offline. We are online.
What are we – the Borg?

The marketer says:
“architect our software”
“leverage our knowledge”
“empower our synergy”
Marketers…
Such funny creatures

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

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

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

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

The PDF file size – so very large!
The business analyst asks:
“Can’t we just use
a smaller font?”
Must control
fist of death

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

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

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

The 2,000 page document is complete
Peace at last
What – more changes?
I insert the CD ROM
delicately into
the reviewer’s skull

The nervous tech writing students
Await my interview of them
Entering as the Emperor, I bellow
“Bring me that one –
He amuses me.”

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

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

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

343 screenshots
All to be redone
Years later, from the tech writing department
You can still hear the screams

See the SME
who does not return his draft
See Igor, the seven foot tech writer
Run, SME, run!

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

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

The Da Vinci XML Code

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

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

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

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

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

Conspiring the Theorists

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Remembering the Future

Related imageTime travel is an endlessly fascinating theme in science fiction; there is no shortage of novels, movies and TV shows that explore it. But is time travel only science fiction, or is it really possible?

How Do I Time Travel? Let Me Count the Ways…
In fact, we are all time travelers – we move forward at the rate of one day per day. Of course, the dream is to accelerate this rate, or even better, go backwards. Various scientific theories suggest how this might be possible (I will tell you now that I have tried them all and none of them worked).

  • Black holes – Black holes are formed after a large star collapses at the end of its life and is crushed into a small point in space. Black holes have such a powerful gravitational pull that nothing, not even light, can escape from them. Now, if you could travel into a black hole and come out the other end (wherever that is), you could, in theory, come out at a different point in time. There is just one small problem – you would have been crushed into nothing before you even entered the black hole.
  • Wormholes – Wormholes are better candidates for time travel. Think of wormholes as shortcuts in the universe. To visualize this, spread out the fingers of your hand. Notice the distance from the tip of your forefinger to the tip of your thumb. Now fold your hand inward, so that your forefinger is only a few millimeters from your thumb. Then picture a small tube, like a straw, held between your thumb and forefinger.Your flat hand represents regular space. Your folded handed represents the idea of “folded” or “warped” space. The tube represents a wormhole – a tunnel that joins these two areas of folded space. If you could travel through this tunnel, you would end up in a different time and place. However, no one even knows whether wormholes exist.
  • Cosmic Strings – These are defects in the space-time continuum that may have been created many billions of years ago when the universe was formed. They are thinner than atoms and, like black holes, generate an enormous amount of gravitational pull, warping the space-time continuum. But, as with wormholes, no one is even sure they exist.

So there you have it. Of the three possible ways to travel through time, one would turn you into spaghetti and other two may not even exist (and if they do, would probably also turn you into spaghetti or some other pasta). We are going to have to look outside of science if we really want to travel through time.

Travelling through Documentation
One solution may already be under our noses. It is something we work with every day and that millions of people use – documentation. Think about it – what is it that distinguishes technical documentation from literature? It is that literature, like time, is linear. People read novels from the beginning to the end, but they read documentation non-linearly. They usually go directly to the topic they need, read it, and then continue on. Later, they may return to a topic on a previous page, then skip directly to one later in the document. There is little concept of “before” and “after” within a document, except within a specific topic, which should be read from start to finish.

This method of “traveling” through a document is even more apparent with online documentation, which contains hyperlinks. Hyperlinks are the wormholes in a document, or in any website. I can think of no other technology that allows you to so easily move from one location to another than a hyperlinked document or website. Imagining trying to describe this technology to people 50 years ago – they would have no idea what you were talking about.

Time Travel on the Digital Express
We live in a digital age. It is quite easy to take photos and videos of your life, dump them onto a computer and then browse through them with complete disregard for chronological order. Technology has enabled us to become virtual time travelers.

At this point you may be thinking, “this is all well and good, but I still want to actually travel through time.” This raises the obvious question: why are we so fascinated with the idea of time travel, especially with traveling back?

Back to the Future
I think it is because deep down, many people wish they could go back in time and change some of the decisions they made. Maybe they would have chosen another profession, another place to live, another partner – the possibilities are endless. Our lives are the sum totals of the choices we have made. We try hard to make the right decisions, but it is only natural to regret some of them. We think “if only” – if only I had done this, if only I had not done that. If, if, if – as they say: “if” is the middle word in “life”.

We may think that if we could go back in time, we could easily repair our lives. The problem is that every decision may trigger a new series of events, and new sets of decisions. Even the smallest change can have huge and unpredictable consequences. This theory is known as “The Butterfly Effect”, so named because of the idea that even the flapping of a butterfly’s wings can create a ripple effect which can ultimately change the weather. So before you go traveling back in time, be aware of the consequences.

Paradoxes and Other Puzzles
Another problem with traveling back in time is all the messy paradoxes it creates. If you go back in time and kill your parents (or, for the less violent among you, simply prevent them from meeting), how could you have been born in the first place? One solution to this problem is alternate universes, the idea that our universe is only one of an infinite series of universes, each containing a different history with different events. In such a scenario, you could prevent your parents from meeting and still be born. The universe would “split” into two – one in which you existed; the other in which you did not.

Keeping all of this in mind, I will demonstrate that in fact, you can go back in time and change the choices you make. If you recall in an earlier column, I demonstrated that our perceptions ultimately determine what exists. That is, our perceptions are reality. So try perceiving this:

Time Travel – The User Guide
Close your eyes (not now, because then you will not be able to read the rest of this column) and imagine moving forward in time. You are drifting ahead through the years… 2010…2020…2030…You are now 85 years old. You are sitting alone peacefully in a comfortable chair in your home. You are looking back on your life and thinking, “if I could do it all again, what would I have done differently? What choices should I have made?” You close your eyes and actually begin moving back in time. 2040…2030…2020…2010…2006. You have been miraculously transported back to 2006.

You have now been given a second chance. What will you do with it?

Don’t Forget to Remember
It is easy to remember the past – it has already happened and you cannot change it. We can, however, change the future and the present. In fact, we are living in the days of future past – something we call “the present”. We must remember that we have a future, and our decisions affect it. Do not forget your past, be aware of the present, but remember the future.