Synecdoche, Technical Writer

Think 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 Blogger 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 Blogger access terminated
**************************************

Read More

A Tech Writer's Guide to the Recession

Stock markets – down.
House prices – down.
Oil prices – down.
Employment – down.
Consumer confidence – down.
Consumer spending – down.
The "Big Three" car makers – going down.

Misery – up.

All this talk of a depression is so....depressing. Still, it is what can happen when the economies of nations are so intertwined, so "single-sourced". America sneezes, and the world throws up.

Recession, The Great Clarifier

A recession (also know as "depression-lite") clarifies things. It exposes the reality of buying objects we don't need using money we don't have.

This is effectively illustrated on the show Till Debt Do Us Part. Each week, host Gail Vaz-Oxlade, who is incredibly obnoxious and pushy, but in a practical and charming sort of way, examines the insane spending practices of a lucky couple. She gives them various financial and relationship-building exercises to perform. If they succeed, they get a modest cash reward, which I'm sure they then spend on a 52" mega TV after the cameras have stopped rolling.

It's an entertaining show, but I can save you the trouble of watching it. Here's the formula for financial success:

earnings minus expenditures = X

• If X is a positive number, then you are on the right track.
• If X is a negative number, then you are in trouble.
• If X is an extremely negative number, then you are extremely screwed.

The recession has revealed our spending insanity on a global level. Out of this financial nightmare, fewer people will spend more than they have. There is a word to describe this type of controlled spending. The word is: normal.

Tech Comm Survivor - Outwit, Outplay, Outwrite

No doubt we are in very painful times. And the question every technical communicator is asking, indeed the question every working person is asking, is simple: how can I survive?

I have a bold solution:

Cease to be a technical writer.

That's right. Stop.

Stop now.

Have you stopped?

Do not be just a technical writer. Instead, be more.

Technical Writer +

Technical communication involves so much more than writing. In fact, it can involve any of the following jobs:

• Information Analyst - review documents, specifications, white papers, design papers, needs requirements, and marketing material
  
• Project Manager - plan, estimate, forecast, juggle, execute, and track multiple documentation projects simultaneously
  
• Software Tester - use, abuse and expose the software and all its flaws
  
• Content Manager - manage, update, and control thousands of pages of content; have an immediate answer when asked where a guide is at
  
• Marketing Communicator - write release notes and other marketing material
  
• Coding Analyst - analyze and describe samples of code, possibly even add comments directly to the code
  
• XML Expert - structure and tag content using XML tags
  
• Error Message Author - write clear, concise error messages that indicate what the problem is and what the user needs to do to solve it
  
• User Interface Designer - correct all the mangled or missing text that appears in the interface, including screen and dialog box titles, buttons and on-screen instructions; give improvements to the layout and design to make it easier for the user to actually use the product, rather than allowing the engineers to create a nightmare
  
• Personnel Manager - juggle developers, salespeople, marketers, QA testers, managers, customers and other technical writers with one hand as you develop and execute your documentation
  
• Investigative Reporter - research, interview, probe, question, doubt, argue, threaten to expose, take nothing for granted, assume nothing, and get a second or third opinion
  
  and, most importantly:
  
• Business Analyst - understand what the end users need to do their jobs and not only create documentation accordingly, but suggest changes to the product you are documenting

Oh, and in between all these jobs, you may do some writing too.

Recession Recap

This recession will:

• stop people from spending more than they have
• force companies that are weak to either change or cease to exist, and as a result:
• force companies to ask for even more from their workers

The more jobs you have been working in your current job, the more valuable you will be. And if you haven't been doing these other jobs, then good news: today is the first day of the rest of your working life.

Read More

Information Architecture

At the office of the TTC (Toronto's public transportation utility), I patiently wait in line to pay a fee. Finally arriving at an open kiosk, the clerk behind the glass prepares a document for me to sign.

The opening in the clerk's window had a small arc-shaped hole.To pass the document through, the clerk substantially crumples it. I sign the form, mash it up again, and stuff it back through the arc.

This collateral documentation damage could have easily been avoided if the designer for this office had factored in the design of the paperwork used in the office. They might have developed a window opening with a wide slot at the bottom, like this:



Form really does follow function. Too bad more interior designers don't do windows.

Now, you may ask: why do I write about things like this?

Because I'm crazy, that's why.

Read More

A Killer Manual

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.

Read More

Size Matters

If you've been following this blog to any degree, you'll have noticed I write three types of articles:

1. Small
2. Medium
and, last but not least,
3. Large

The size of the article is directly proportional to the number of words required; no more and no fewer. (This, by the way, is a general principle to follow in technical communication.)

It's like food: sometimes you just need a snack, other times a regular meal, and, once in a while, an enormous, gut-bursting, three-belt notch loosening meal - the latter popular during this holiday season.

Enjoy this snack. More delectables to follow.

Read More

Single-Sourcing My Life

I was determined to avoid email bankruptcy, the fate of Internet commentator and legal expert Lawrence Lessing. Lesson was so overwhelmed with the volume of emails he received that he sent a mass email back saying he'd probably be unable to respond.

My problem was not the volume of email, but the fact my contact information was spread out over many different files, and over several different computers. I use up to four different computers a week, so I knew I had to get my email on the Net. After much informational detective work, I consolidated all my contacts' email addresses, phone numbers and other data into a single online location. It's a beautiful thing.

You've Got Mail (And A Bunch of Other Stuff Too)

Of course, being an "info junkie", I couldn't stop at email. I also moved my web favorites online, as well as certain documents that I wanted to view and edit anywhere, just like this Blog. (This comes in handy when your teen-aged daughter kicks you off the computer.)

The Battle for Storage: Please Take It Offline

Clearly, online storage has its advantages. However, so does storing files locally, as the following list indicates:

Access to Files:
* Local Files: Limited to specific computer only
* Online Files: Any computer with Internet access

Application Features:
* Local Files: Many
* Online Files: Fewer, but growing

Application Updates:
* Local Files: Less frequent
* Online Files: More frequent, and often free!
Ability for others to comment and add metadata:
* Local Files: Limited
* Online Files: Widespread

Speed:
* Local Files: Fast
* Online Files: Slower, but getting faster

Security/Privacy:
* Local Files: Better
* Online Files: Potential risk

Backing up:
* Local Files: Must do
* Online Files: Somewhat optional; data is stored "off-site"

Potential for duplicate data:
* Local Files: High
* Online Files: None

If Internet connection is down:
* Local Files: Can still access files
* Online Files: The horror, the horror

As Internet speed, technology, features and security improve, more people will shift their information away from a specific machine and onto the Web. In fact, in the not too distant future, we'll just log on to any machine anywhere, and have immediate access not only to all our files, but our entire desktop and all our custom settings and applications. The customizable websites of today (such as iGoogle, Yahoo and Facebook) are but a taste of tomorrow.

Lining Up Online and Offline

The amount of information we already access online is extraordinary. Banking sites, social and professional networking sites, and blogs are all accessible anywhere. Yet there is still much data trapped within our specific machines.

For example, I haven't really single-sourced all my contact information. It's still duplicated in Microsoft Works where I can create custom lists and reports, and again in the speed-dial information on my various phones. True single-sourcing would allow us to enter the information once and use it on any device, reformatting as necessary.
Feed Me

An excellent example of this type of content reuse is found in the wide variety of RSS readers. (This blog automatically creates an RSS feed.) All RSS feeds are in a standard XML format, allowing you to follow them using the readers (or browser) of your choice. Most importantly, you can change the appearance of the information, sort it and categorize it.

The Para-Docs

Now, technical communicators, being the "techie" types we are, are heavy creators and users of customized Internet data. This leads to a rather odd paradox.

During our personal time, we create and store data on the Internet, with all its inherent advantages. Then, during our working time, we manage documents that we can edit only on one computer - our company desktop or laptop. Even those of use who are lucky enough to work at home occasionally still have to schlep our laptop back and forth to work. Finally, the documents we work on are printed or packaged with the software. The layout and formatting are fixed and the content is frozen.

They say that a picture is worth a thousand words - what's wrong with words in this picture?

Some companies are beginning to realize the absurdity of creating documents that can become outdated moments after they are produced. As a result, these businesses are providing more of their content within secure online locations. PDFs and Word files may be quick and easy to produce, but they represent an antiquated model of communication.

Don't Bury Me - I'm Not Dead Yet!

Of course, traditional documentation won't completely die. They'll always be a need for hard copies, especially for hardware and other equipment, where printed quick start and setup guides are essential. However, we will see more content shifting online, as companies strive to cut costs and stay current.

Don't WORA, Be Happy!

Java developers say: write once, run anywhere (WORA) to indicate that they only have to write a program once and it will run correctly, regardless of the platform.

Information developers need to say: write once, access anywhere. Create, edit and read what you want, where you want, when you want and how you want. Otherwise, we'll all be declaring documentation bankruptcy.

Read More

Losing Focus

Is it too late to write about Stéphane Dion's ill-fated video response to the Prime Minister's professionally produced presentation? Dion's rambling video not only arrived late to the networks, but was out of focus and improperly framed. It did more to end his short-lived career as opposition leader than anything else. It is for people such as Dion that words such as hapless were created.

An article in Maclean's revealed the source of this debacle. Apparently, Dion was so obsessed over the content of his presentation that there was not enough time to shoot it properly. As a result, history is left with a film that makes You Tube look like an IMAX theatre.

A fool learns from his own mistakes; a wise man learns from the mistakes of fools, and there is no greater fool than Dion. All communication, whether video, audio or textual, is made up of content and form. Content is the pure substance of the message; form is the wrapper the message rests in. Even if Dion's content had been perfect, its form was so flawed that it effectively hid the content.

It's easy for technical communicators to become so obsessed over the content that they forget the form. The most well-written and well-researched document will be rendered nearly useless if the presentation of the information is poor.

A checklist is a beautiful thing. Before releasing the final version of the document you sweated over, do a formal form check:

1. Is the cover page correct, including the logo, title, version number, and author?


2. Have you included all the standard, common sections such as legal and copyright information, document conventions, support and contact information, and standard product information?


3. Is the table of contents correct and current?


4. Are all headers, footers, and page numbers visible and correct?


5. Are all the chapter names and numbers correct?


6. Are the various headings and paragraph styles correct? Is all numbering properly sequential?


7. Are all your variable values, conditions, and reused text sections correct?


8. Are your margins consistent?


9. Are there any missing or poor quality graphics?


10. Have you updated you index to reflect your new, changed and deleted topics?
    
11. Have you run a spellcheck?


12. Does your released document have the correct filename?


13. Have you checked all these things one more time?

It is all too easy to get lost in the words and forget their container. Do not rush. Plan for and use the extra time to check everything. Otherwise, you'll be the Dion of Documentation.

Read More

Facing Off New Technology

A remarkable event occurred in Cleveland a few weeks ago. In a marathon surgical procedure, a team of eight doctors worked 22 hours to transplant a woman's face, moving bone, teeth, muscle and nerves. It was the first facial transplant in the United States, and only the fourth in history.

One of the doctors vividly described the procedure: "We transferred the skin, all the facial muscles in the upper face and mid-face, the upper lip, all of the nose, most of the sinuses around the nose, the upper jaw including the teeth, the facial nerve." These incredible technical craftsmen have truly "saved face".

I remember the 1997 action science-fiction film Face/Off. In it, a policeman and a criminal mastermind switch identities through a facial transplant, with rather unexpected results. Science fiction has become science fact.

Now, if these doctors can transform a person's face, it obliterates all excuses for not transforming the way we create documentation. Converting thousands of pages of legacy documentation to a structured format is very difficult. But impossible? Impossible occurs when you lack either the will or the means to accomplish something. Let this event in Cleveland inspire us all.

Read More

Cheques and Balances

I recently submitted three cheques to an individual, verbally indicating to him that two of the cheques were post-dated. Naturally, his office worker promptly deposited all three cheques, thereby incurring two NSF charges.

Just as doctors make the worst patients, technical communicators often neglect to write instructions down. What we have here is a failure to communicate. They say hindsight is 20/20, but 20/20 simply denotes average (not superior) vision. As professional communicators, we need to be far above average in our written instructions.

Therefore, in superior hindsight, I would have documented the cheques as follows:

1. A note written on the cheques themselves stating POST-DATED, highlighted in screaming bright yellow.
   
2. A florescent post-it note placed on the cheques, again indicating the cheques were POST-DATED.
   
3. A letter with the cheques in an envelope, again indicating the cheques were post-dated, and listing the amounts, cheque numbers and dates of each cheque, with explicit instructions not to deposit the cheques until their date arrives.
   
4. A note on the envelope itself: POST-DATED CHEQUES ENCLOSED!

Overkill? Most probably. Would it have avoided the user error? Most probably. In documentation, assume the user will err, and use all your communicative powers to prevent it.

Read More