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

The Fractal Factor

They're in the sky, on the ground, in nature, clothing, special effects and even your cell phone. They're incredibly simple yet extraordinarily complex. The closer you get to some of them, the further away they seem. They are fractals and they're everywhere.

Fractals are complex, irregular, endlessly repeating geometric shapes. They can be easily created on a computer but also occur naturally. The classic example is a tree.

It's Only Natural to Love Fractals

When you look closely at a tree, you'll see a main section, with branches protruding outwardly from it. Each branch, in turn, is like a mini-tree, with sub-branches sprouting off the main branch. Each sub-branch may also contain a sub-branch. In other words, the tree shape repeats throughout the tree.

Another example is a coastline, which has a certain irregularity or "crinkliness" to its shape. You'll see the same degree of crinkliness when viewing the coastline from 1 metre, 100 metres, a kilometre or even 10 kilometres - the overall pattern remains the same.

Mountains, flowers, clouds, plants and snowflakes - all of these naturally occurring things are fractals. However, it's only recently that fractals have been recognized as much more than just pretty patterns. They have real, practical applications in both science and mathematics.

Fractal-shaped antennas are used in mobile devices such as cell phones. It's been scientifically proven that this type of antenna shape is the most efficient at receiving the widest variety of signals. Without it, your cell phone would resemble a porcupine because it would require so many different antennas.

Many cinematic special effects use fractals. The spectacular lava effects in the finale of the last Star Wars film, Revenge of the Sith, were generated using fractals. Fractals are also used in design, engineering and medicine.

Computer-generated fractals have a particularly unusual property: no matter how much you magnify them, the level of detail does not change. You can see an animated example here.

Info-Fractals

New technology has unknowingly fractalized information. The best example of this is Wikipedia. Open any major topic and you'll see it's very detailed and contains dozens, if not hundreds, of hyperlinks. Click the hyperlink within this topic, and it takes you to another detailed topic, again with its own set of hyperlinks. As with fractals, the level of detail remains about the same no matter how much you "zoom in". This fractalization does not just exist with websites. A complex online help system also allows you to move from one topic to another, with little or no diminishment of detail.

Just as fractals have no real start or end, neither do modern information structures. Although technically both Wikipedia and an online help system have a first and last topic, from the user's perspective, they do not. Users rarely read documentation linearly - they go directly to the topic they need, perhaps follow some links to get additional information and then they leave. Documentation is not a novel.

Modern documentation, therefore, clearly resembles fractals. However, there is another more important similarity, and to understand it, you need to look at the history of fractals.

Math Wars

Benoît Mandelbrot (1924-), is considered the father of fractals. When he first presented his theories, the mathematical community did not take him seriously. They thought the shapes he created were "pretty" but had no practical applications and therefore did not represent genuine mathematics.

These mathematicians were trapped in their traditional, Euclidean view of mathematics: straight lines, simple curves and basic shapes. They simply could not fathom a math that was so irregular. Many years would pass before other mathematicians finally recognized Mandelbrot's work as genuine mathematics.

Believe It or Not

Our profession suffers from similar disbelief. It's held by writers who are unable to accept the new way of creating information, specifically XML, where all information is classified by tags and which separates the form from the content.

XML is as different from traditional documentation as fractals are from traditional mathematics. As an example, you may be used to this way of writing:

Printing a Page (Heading 3 paragraph style)

1. From the File menu, select Print. (Numbered paragraph style)
2. Select your print options. (Numbered paragraph style)
3. Click Print. (Numbered paragraph style)
The document prints. (Body paragraph style)

Now try this way of writing:

[procedure title]Printing a Page[/procedure title]
[step]From the [UI element]File[/UI element] menu, select [UI element]Print[/UI element].[/step]
[step]Select your print options.[/step]
[step]Click [UI element]Print[/UI element].[/step]
[result]The document prints.[result]
Note: In XML, greater than (>) and less than (<) signs are used, not square brackets. However, because Blogger does not allow you to enter these characters in pairs, I used square brackets in this example.

Ugly, isn't it? There's no formatting or paragraph styles, just tags. Note that this is an extremely simple example. Still, many writers will balk at this and say it's not really technical writing but "programming" or "coding".

An Inconvenient Truth

Just as traditional mathematicians initially refused to accept fractals as actual mathematics, many writers are unable to accept XML as actual information development. However, XML is, in fact, information development in its purest form, because it separates the form of the information (the fonts, point sizes, formatting and layout) from the actual content. In addition, XML allows you to modify, manipulate and manage information in ways that are simply impossible using traditional documentation methods.

The choice is ours: we can continue our old ways, or we can change. If you're struggling with the new ways, then remember the lowly fractal the next time your cell phone rings. If it weren't for one person challenging the system, you'd never be able to get that all-important call.

Read More

The Colour of Notes

Positively Autistic is a fascinating CBC Newsworld documentary about autism. Its premise is that people with autism do not really need to be cured, and that society should just accept them as they are, in the same way we accept differences in race, religion, sex and other innate characteristics.

One of the individuals profiled is Amanda Baggs, an eloquent autism-rights activist who runs her own blog. She does not speak, at least not directly. Instead, she types out what she wants to say, and then a voice synthesizer does the talking for her. Baggs also posts videos to YouTube that describe how she experiences autism. One of her videos, In My Language, has been viewed about 700,000 times.

Baggs describes how she perceives sounds, and in doing so shines a tremendous light on how all of us perceive things. Incredibly, she is able to identify various musical notes as easily as you or I can identify colours. In other words, she is able to see the exact "colour" of the note.

All this raises an interesting question: who exactly has the disability? On what basis do we say that the inability to recognize musical notes is acceptable, but the inability to socially connect with others (a characteristic of many autistic people) is unacceptable?

Clearly, the ability to identify musical notes is a gift. In fact, it is one of many gifts that autistic individuals have. Other gifts include the tremendous ability to focus on specific details, an incredible memory, and extraordinary technical capabilities. Many of the technological advances in society (from computers to cell phones) would not have occurred had there not been people at least partially on the autistic spectrum to develop them.

I've often said that technical writing requires a somewhat autistic personality. Technical writers are hyper-sensitive to specific words and text, just as some autistic people are hyper-sensitive to sound or colours. Whenever I see poorly written instructions, or, worse, discover that the instructions are missing altogether, it stresses me out. (Not to the point where I need to be severely medicated, but pretty close.)

As writers, we obsess not only over the words we write, but their appearance. Take the following instruction, for example:

It is important to back up your files.

That's true, but this doesn't really tell you what to do. How about:

Ensure you back up your files.

This is better, but it doesn't tell you how often to do it. Let's try:

Ensure you back up your files at least once a week.

That's specific enough for our purposes, but how can we make it stand out a bit more? Adding one word helps:

Note: Ensure you back up your files at least once a week.

We're getting there, but we need additional emphasis:
Important! Ensure you back up your files at least once a week.

Finally a dash of colour to this note to make it really stand out:
Important! Ensure you back up your files at least once a week.

Now, dear reader, do you honestly believe that most people would pay so much attention to a single line of text? Of course not - they have other things to do with their lives. Technical writing is a mental condition like autism, and like autism, it can be a positive thing. Learn to embrace your insanity: it positively colours everything you do.

Read More

Political Interchange

Politicians are the masters of interchangeability. They often do and say the same things. This comes in handy whenever they have to develop policy - they simply lift it from another party, giving new meaning to the term "single-sourcing".

Where politicians especially excel is in their use of political slogans. You can take almost any slogan or expression from one party and reuse it in another. Here's a few examples, culled from the websites of various political parties, and from my vivid imagination:

Strong leadership
Tough times demand leadership to pull us together
Leadership certainty for Canada's economy

A vision for the future
Clear direction for a brighter future
Working for your future
Helping families get ahead
Working for your family
Expanding opportunities for families
It’s time for a Prime Minister who’ll respect your vote
Giving everyone a fair shot
Making a difference
We’ll always be on your side
Looking out for your interests
For a richer, fairer Canada
Putting families first
Putting farmers first
Putting workers first
We'll invest in your future
Let's unite for the future
Looking out for your future
We're a big tent party
Getting the job done right
Taking action on the economy
Protecting your job
Protecting your future
Protecting natural resources
A clear choice
A new choice
A strong choice
A choice of hope and optimism
Facing a critical choice

Text like this is reused, quite literally, across different (party) platforms. When developing documentation that will be reused, keep the principle of interchangeability in mind. The following example illustrates this:

You are documenting a set of installation guides for various products and want to reuse text where possible. One of the steps common to all products is:

From the installation CD, run Setup.exe.

The problem is that only some of the products are installed from CDs, while others are downloaded. If you want to reuse this step, you'd need to reword it to be fully interchangeable.

You could say:
From the installation package, run Setup.exe.

Or better still: Run Setup.exe.

The last choice is the simplest. It assumes the user knows where to find the setup file. If they don't, they probably shouldn't be installing the program!

Writers have a saying: "write what you know." Technical writers need to "write what they know could be reused anywhere."

Read More

Interviewing for the Job and On The Job - Part III

This article is the last of three in a series. It’s based on my presentation at the STC Career Day and describes the six basic principles to follow for both job interviewing and informational interviewing.

5. Get another job.

No, I don't mean quit your job. Instead, recognize that there are aspects of many other professions within ours. You need to take on these other jobs during interviews, especially informational interviews.

Elementary, My Dear Watson

Firstly, you need to be a detective, a true Sherlock Holmes. Before a job interview, research the company and study their financial information. During the interview, look for clues that this may or may not be the right job. Arrive at the interview early, read any company literature in the lobby and observe any activity. During the interview, take note of how the interviewers behave, and listen carefully to what they say. How old is the documentation software they are using? Is documentation considered an integral part of the product development process, or is it just an afterthought? Do the questioners seemly overly anxious to hire you? Gather these clues to make an informed choice if you’re presented with an offer.

For informational interviews, recognize that the product you are documenting is a mystery that you must solve. All sorts of questions will arise as you create your documents, and the answers are not always clear. For example, a database I was documenting contained a field that no-one seemed to know about. After considerable investigating, I found out it was only present to ensure backwards compatibility, and documented this accordingly. On another project, I couldn’t figure out why I was unable to delete a user record. It turned out administrative rights were required. Again, this had had never been clearly documented. Follow the clues and the truth will be revealed.

Investigating the Truth

Similarly, you need to be a journalist, or better still, an investigative reporter. A good reporter always questions the status quo, and is healthily skeptical. That is how they are able to reveal the hidden truths that those in power wish to hide. You need to practice doubting, which is a skill like any other. A good way to develop it is study viewpoints that are diametrically opposed to your own on such controversial topics as politics, abortion, the Middle East, and the wars on terror and drugs. Reasonable people can hold opposing view on these topics. By studying alternate views, you are training your mind to question things.

Being an investigative reporter applies mostly to informational interviewing, including interviews about the documentation in general. For example, my co-worker and I questioned whether our ReadMe files really needed to be in text (.TXT) files, which is a very limited and cumbersome format. We investigated and discovered we could change them to the much more flexible RTF and PDF formats, with all of their inherit advantages. Had we not questioned this, we’d still be stuck with the old formats.

Trust, but Verify

During your investigations, recognize that ultimately you can only know what you can verify. For everything else, you have to trust others, so consider the source and their interests.

For example, there was an unusual documentation issue at the 2008 Olympics in Beijing. Some of the female gymnasts appeared to be below the age limit. As “proof,” passport documents of the athletes were presented showing their birthdates. Who issued the passports? The Chinese government. Who benefited from this? The Chinese government. How do you say "conflict of interest" in Mandarin?

In software, a developer may be reluctant to tell you something is not working, if they are going to have to be the one to fix it. A product manager may not like being told that the instructions on a screen are unclear, if the product manager wrote them. A good technical writer rises above all this, and does what’s best for the end user.

Document Diplomacy

Dealing with conflicts such as this means you also have to be an ambassador and diplomat. As an ambassador, your job is to bring two groups of people together: those who create the applications and those who use them. In doing so, you help solve misunderstandings and miscommunications between these two groups, just as a real ambassador does between two countries. You may even prevent a thermo-nuclear war.

Interpreting the Results

You also need to be an interpreter, which is quite different from a translator. An interpreter extracts the real, intended meaning from something, and this can often involve a complete rewording. For example, there may a screen that says, "Click here to enter application." Does this mean click to type in the name of the application or click to actually open the application? It’s not clear from the wording. As an interpreter, you would reword this text to remove all ambiguity. Interpretation is also an important skill to have when working with error messages, which are often unclear and do not state a solution.

Mind Games

Finally, you need to be a psychologist. You need to understand the mindset of both the users you are writing for and the people you are interviewing. For example, developers are, for lack of a better word, autistic. (I have a son with autism, so I know a bit about it.) Autism is a condition of the mind in which a person is able to have incredible focus on specific details but is unable to connect with others or see “the big picture.”

To illustrate this, imagine a child named Alice holding a ball. She places the ball inside the first of two boxes in a room, closes the lid, then leaves the room. A second child enters the room, moves the ball to the second box, closes the lid and then leaves. Alice returns and is looking for her ball. The question is: where will she look for it? The obvious answer is the first box, the one that she left it in before it was moved.

However, when you describe this scenario to an autistic child, they will answer that Alice will look for the ball in the second box. When you ask them why, they will respond “because that’s where it is.” Incredibly, the autistic child does not realize that what they know is different from what others know. That is why autism is called a form of mind blindness, because it causes a person to be unable to comprehend another’s point of view.

Calling All Developers

Developers often exhibit these tendencies. For example, a developer may be asked to create a work phone number field for a customer information screen. They will neglect to leave room to enter a phone number extension, even though the developer’s phone has a phone number extension. They are not stupid – they simply cannot make the connection.

Therefore, your job, as a psychologist, is not to be mind-blind, but mindful. Stop and see the big picture when gathering information. Is there anything missing? Is there something there that shouldn’t be? Is this something an end user can actually use and understand? By being mindful of your SMEs and end users, you will create documents that are much more usable, accurate and complete.

6. Go to 11.

1984 was an interesting year. It was the year George Orwell’s dark novel was named after. On a lighter note, it was also the year that the film This Is Spinal Tap was released.

The film is an mockumentary of a fictitious, aging British heavy-metal band named Spinal Tap. The band members are hilariously portrayed as dimwits. In a classic scene, the lead guitarist, Nigel, shows off an unusual amplifier to the interviewer, Marty DiBergi:

Nigel: The numbers all go to eleven. Look, right across the board, eleven, eleven, eleven and...
Marty: Oh, I see. And most amps go up to ten?
Nigel: Exactly.
Marty: Does that mean it's louder? Is it any louder?
Nigel: Well, it's one louder, isn't it? It's not ten. You see, most blokes, you know, will be playing at ten. You're on ten here, all the way up, all the way up, all the way up, you're on ten on your guitar. Where can you go from there? Where?
Marty: I don't know.
Nigel: Nowhere. Exactly. What we do is, if we need that extra push over the cliff, you know what we do?
Marty: Put it up to eleven.
Nigel: Eleven. Exactly. One louder.
Marty: Why don't you just make ten louder and make ten be the top number and make that a little louder?
Nigel: [long, awkward pause] These go to eleven.

The expression “going to eleven” has come to mean giving it that little bit extra, or as we say in the business world, giving it 110%. Often a little difference makes all the difference. It can mean the difference between winning a gold medal and winning nothing.

Going Beyond

In a job interview, go beyond the minimum by following all of the principles described in this series. Dress sharp. Practice your responses and your questions. Show passion for the job and your work. Describe how technical writing is not just your job – it’s your religion. Talk about how you are involved in outside activities and groups that involve technical writing, such as the STC or Editors' Association of Canada. If you’ve done volunteer writing for charitable organizations, describe it. Most of all, show how you’ve gone the extra mile in creating and improving your documentation.

Letter Perfect

For example, our FrameMaker templates used to be an odd size: approximately 5” x 9”. This is because we used to send our documents to a printing house, and that was the size of the manuals they produced. Later, we stopped having them printed this way, and simply created PDFs, but they were still at this odd size. Customers were wasting paper because they were printing the files on letter-size paper. I decided to change the templates to letter size, or 8 ½ x 11. That's right - my templates do indeed go to eleven.

Summing Up

These are the six basic principles of effective job and informational interviewing. If you study them, and practice them, then everyone will say of you, "there goes a great tech writer, because that tech writer goes to eleven."

Read More

Interviewing for the Job and On The Job - Part II

This article is the second of three in a series. It’s describes the six basic principles to follow for both job interviewing and informational interviewing.

3. Honestly, Now

I remember a strange incident at my workplace years ago. A manager kept popping out of his office, bursting with laughter. He was fact-checking a job applicant’s resume, and discovered that almost everything on it was a lie: where the applicant went to school, where he worked, the groups he belonged to, and so on. Each time the manager confirmed another lie, he couldn’t wait to fly out of his office and laughingly inform the other managers.

I often thought about that job applicant. What was he thinking? Was he thinking? What if the manager hadn’t checked the resume, and the applicant had been hired? For the answer, we need to look to history.

King Pyrrhus vs. The Romans

Many years ago, a Greek King named Pyrrhus defeated the Romans, the superpower of the time. This was an incredible feat – it would be like Mexico beating the United States. (Can you imagine what would happen? There’d be millions of Mexicans living in America and the government would be trillions of dollars in debt…OK, bad example.) In any case, although Pyrrhus defeated the Romans, he did so at enormous cost – many of his men were slaughtered. That is, he won, but he lost, hence the expression Pyrrhic victory; a victory that really isn’t much of a victory.

So it is with applicants who lie their way to a job. They get the job – now what? They’ve got a job that they are not qualified to do, that requires skills they don’t have, at a place they don’t want to be, working with people they can’t stand – congratulations! When you lie or embellish the facts on your resume or in an interview, you’re only lying to yourself.

Therefore, in an interview, always be honest. If you don’t know how to use a particular piece of software, say so, but also describe how you are a quick learner. If you worked on a project that went bad, be honest about it, but say what you learned from the experience. A little honesty goes along way.

For example, if asked, "Why should we hire you?" answer the question honestly. State how you sincerely believe that you’d be a good fit for this position, and that you have much to offer.

Another question that will test your honesty is: Tell me about a time you failed. Without hesitating, state the failure, but then explain how you learned from it. For example, perhaps you were rushed and released a user guide that you later discovered was missing certain procedures. Talk about how you learned from this, and more carefully planned your schedules and reviews, so that the next release was better than ever.

By the way, this question is a good example of a stress question, where the interviewer wants to see your reaction, and is not just concerned with the content of your response. Be strong and show how you can easily handle the pressure.

Fool Me Once, Fool Me Again, Please!

Honesty also applies to informational interviewing. Often times, when interviewing the SMEs, we’re too embarrassed to admit we don’t understand something. Just remember – it is your job as a professional informational developer to go from not understanding something to understanding it. If you are not initially confused and bewildered, then you’re not doing you’re job. If you don’t understand something, say so! You may look foolish – so what? It’s better to be a fool in private that to create foolish documents, documents that may come back to haunt you – then you’ll really be the fool.

Chaos Theory

All great products and services got to be great by having people ask dumb questions. There’s so much chaos that we don’t see. If you’ve ever been backstage at fashion show or a play, you’ll see it’s often total mayhem – people yelling and screaming at each other, doing dumb things, and asking dumb questions. But the audience never sees this– they just see a beautiful show, or a beautifully complete and concise document.

4. Don’t Be Anti-Active; Be a Pro

It’s no coincidence that the words professional and proactive both begin with the same three letters. To be a professional, you need to be proactive. Proactive should really be called pre-active, to indicate that you take action before (pre) there is a problem, and thereby pre-empt the problem.

Explosive Issues

Being proactive means being responsible, and responsibility is something you hear about in the news all the time. In 2008, there was a huge explosion at a propane facility a few kilometers from our home. We were far enough away that we weren’t directly affected, but we did hear it. Afterwards, almost on queue, no-one wanted to take responsibility for this disaster. The city blamed the licensing facility. The licensing facility blamed the city. The province blamed the city. The city blamed the facility owners. The owners probably blamed the employers. No one wanted to take responsibility.

Compare this with the disaster that followed shortly after, in which various meat products at the Maple Leaf processing plant became infected with listeriosis and several people died. Incredibly, the president of the company, rather than blaming others, took full responsibility. He did not blame the government. He recognized that the buck stopped with him.

Responsibility is an important issue for us, because it relates to the question of who ultimately owns the documentation. The very definition of a senior technical writer is someone who owns, and is therefore ultimately responsible for, the documentation, in the same way that senior coding developers own the code.

Pro-Active Interviewing

Being pro-active and showing responsibility applies in two ways during a job interview. First, you need to be proactive before the interview. Carefully study the company, its history and products, and the position itself. Secondly, show during the interview how you have been proactive in your job. Examples include redesigning the templates, improved the indices, and enhancing the documentation development and review process. Bring samples to indicate the changes you made. Show how you avoided documentation explosions before they happened.

A question you may be asked that will show how proactive you have been is: Why do you want to work here? To answer this question effectively, you must have proactively researched company and the position, and reviewed your skills and work history so that you can clearly state why you’d be a good fit.

Finally, you may be asked: What is the purpose of technical communication? You might think the answer is to instruct the reader on how to use a product. That’s true to some extent, but the real purpose is to reduce technical support costs by creating documents that people actually use, and thereby help avoid the users from having to call in. Therefore, you need to show how you have proactively done this. Examples include creating a detailed troubleshooting section, adding critical missing content, developing training guides, and writing a glossary.

For informational interviewing, being proactive means planning your questions carefully before you sit down with the SME. It means creating documentation plans and schedules, and reviewing and testing the product to find all the hidden and potential problems. It means recognizing that a SME’s time is valuable, so you want to be able to zoom in and get clear answers to your questions by having used and tested the product you are documenting. It also means constantly following up with the SMEs to ensure they answer all your questions and review every draft.

Read More

The Green Machine

Elizabeth May, leader of the Green Party, appeared to have won a major victory by being allowed to participate in the debates for the 2008 federal election. Technical writers are, above all else, a practical tribe, so let's analyze this from a practical perspective, shall we?

Ms. May was allowed into the debates. Did everyone actually watch the debates? No.

But let's say everyone did watch the debates. Would this have necessarily influenced their vote? No.

But let's say it did influence a few votes. With our first-past-the-post voting system, even a major increase in the number votes would not necessarily lead to more seats.

But let's say it did actually lead to more seats. Would it necessarily mean many more seats, to the point where they would actually wield any power? Probably not.

But let's say it did lead to enough seats to actually influence the government. Is there any reason to believe that changes enacted would have a real, practical effect on our daily lives? Again, probably not. In fact, how you manage your career has far greater impact on your wealth and happiness than the act of inscribing an 'X' on a small piece of paper and inserting this into a cardboard box.

Now let's go back to the original issue: whether May should have been allowed in the debates. We're talking about something that probably had no effect on something that will probably have no effect on something that will probably have no effect on something will probably have no effect. In other words, this is an issue where people reacted disproportionately to the importance of the issue.

You may kill yourself trying to write a description of a field in a dialog box, a dialog box that is rarely used, in an application that no longer sells, for a user guide that no one may be reading. Ask yourself - is it worth the effort? Perhaps you should be focusing on improving the documents that people are actually using.

Read More

Taking Stock of Stocks and Docs

It 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.

Read More

Interviewing for the Job and On The Job - Part I

First of three in a series

This article is based on a presentation I gave at the STC Career Day, held at Seneca@York, September 22, 2003. It describes the six basic principles to follow for job interviews and informational interviewing, including asking and answering the right questions, of the right people, at the right time.

The DNA Interview

The science fiction film Gattaca envisions a future where everyone is genetically engineered to be a perfect match for their job. For example, a classical pianist is bred to have an two extra fingers so that he can play more notes. (I presume he would also give good back scratches.)

In a scene from the film, the main character is applying for a job as an astronaut. A lab technician scans a sample of the applicant’s blood to verify that the applicant is who he says he is. (He’s not really, but that’s another story.) The technician tells the applicant he’s hired. The applicant asks, “What about the interview?” to which the technician responds, “That was it.”

Ah, if only it were that simple. If only there was some magical machine that could scan our minds, determine if we were the right fit for the job, and spit out a message: “Technical writer - level 4 – please proceed to your workstation.”

The UnSystem

Alas, there is no such system. Instead we have the following "system": you enter a room with one or more people, answer a series of questions, and based on how well you respond, you get the job. (Your portfolio, while important, cannot salvage a bad interview.)

Now, does this so-called system make any sense? What have you really proven? You haven’t shown you’re the best person for the job – you’ve simply shown that you can answer a series of questions, and that you can find the company's building.

What companies should do, after weeding out the candidates that have truly rotten resumes, is temporarily hire the various applicants to see how well they perform on the job - in other words, apprentice them. This is, in fact, done for certain professions, but not often for technical writers, as it’s a very expensive and cumbersome option.

So we're stuck with the system where the best interviewee (and not necessarily the best candidate) wins the job. Therefore, excellent job interviewing skills are critical. However, as important as these skills are, you'll only need them several times in your life.

Assuming you work about 40 years in your life, for an average of 4 years per job, you'll have experienced ten interviews on ten separate days. On the other hand, while on the job itself, you will be conducting informational interviews all the time, hundreds, if not thousands of times, during your working life. Therefore, good informational interviewing skills are also very important.

Master of Disguise

Job interviewing, is, in fact, just a form of informational interviewing in disguise. Interviewers are trying to obtain as much information about you as possible, and you're trying to get as much information about them, the company and the position as possible, all in a limited amount of time. That’s why these interviews are so stressful.

Also, informational interviewing isn’t used just for finding out information about documentation, but about how things work at your company. The company I work for was recently acquired by Oracle, and we've all been receiving vast amounts of information about the company, the new people and the many new policies and procedures. I’m thankful that as an information developer, I can sort through it all.

Indeed, you can use informational interviewing to find out about anything, including what’s really going on at your company, your family and colleagues, with technology and our profession, with your finances – anything. So you will find it is an extremely useful skill to have, and not just at work.

Let’s now look at the six basic principles of effective job and informational interviewing.

1. Shhhhh - The Audience is Listening

The first principle of interviewing is also a basic principle of information development. It is that before you write a single word of a document, you must know who the document is for and its purpose. In other words, you must know your audience. For example, the readership for a digital camera guide is quite different than for an administrator’s guide that describes how to set up a complex network. You need to target the language, structure and organization of the document accordingly. Ideally, you should imagine that you are that audience.

So it is with interviewing – you need to target your questions and answers to your audience.

The Three Musketeers

In a job interview, you'll typically encounter three different types of interviewers:

1. The HR (human resources) specialist
2. The person you'll potentially be working for
3. The person (or people) you'll potentially be working with

You need to carefully craft your responses for each of these three types.

HR – Humane Responses

HR personal are generally non-technical, and therefore know little about technical writing. Do not talk over their heads with mindless techno-speak. For example, if asked to describe your best accomplishment, don’t respond with something like: “I effectively single source with FrameMaker using a complex combination of text insets, conditional text and variables.” The HR interviewer will silently nod in agreement but will have no clue as to what you just said. Instead phrase your response to their level, for example:

"We had lots of text that kept repeating throughout our documents. Every time it changed, we had to manually find the text in the various documents and change it, which took a lot of time and effort. I was able to fix this problem by storing this recurring text in a single file, and then using references, or pointers, similar to a Windows file shortcut, to repeat the same text in different locations. Now whenever there is a change, I just have to change one file instead of many, and the change magically propagates throughout the entire documentation set, greatly lowering the maintenance.....(Can you dig it? I knew that you could….)"

Don’t Boss Me Around

If you survive the HR gauntlet, you'll be interviewed by the person you could be working for. This is the most important person who will interview you, because it is they who will usually make the final hiring decision.

The person you may work for will be one of two types:

1. A technical writer – e.g., documentation manager, publications manager, technical writing team lead, etc.

2. Not a technical writer – e.g., a development manager, QA manager, product manager, marketing manager, etc.

Again, if they are not a technical writer, don’t use heavy tech writing industry jargon; talk at their level. If they are a technical writer, you can be a bit more technical, but don’t overdo it, as they may think you are trying to mask other problems.

Whether or not your potential boss is a technical writer, what you want to emphasize in your responses is that you are:

flexible and adaptable

a team player – you play nicely with others

friendly and approachable

intelligent, organized, knowledgeable and resourceful

able to hit the ground running with minimal ramp up type – a quick learner

honest and responsible

Just One of the Guys (or Gals)

When being interviewed by the people you may be working with, typically other tech writers, it's very important not to come across as a condescending, obnoxious, know-it-all. Recognize you are at their level, and act accordingly. Share horror stories of tools. Get their advice on a challenge you face. Have a sense of humour - tell them you still have troubling spelling XML and PDF. Show them you can work with them by actually working with them in the interview.

Be Afraid, Be Very Afraid

Be aware that behind every question you’ll be asked is fear – fear that you are not one or more of qualities just listed. Fear that you are unqualified (or overqualified), difficult to get along with (and therefore manage), a liar, a cheat, dishonest, irresponsible, arrogant, stupid or just generally psychotic. You must allay these fears in the interview by giving concrete examples of what a fantastic worker you are. Talk about how you enjoy working with others, how you have made great improvements to the doc set and the doc process, and how you are always learning new things. Most of all, you need to show a genuine and solid interest in the position. Studies show that the candidates who win interviews came across as most passionate for the job.

Be Yourself, Not

As described previously, the principle of knowing your audience obviously applies to informational interviewing, because you have to ask questions that get the answers the typical reader needs. That’s why it’s best if you can imagine you actually are the end user – with all of their needs, wants, fears and neuroses.

This principle applies another way: to the person whom you’re interviewing. You need to understand them and what level they are at, so that you can ask relevant questions.

Nuts and Bolts

Imagine you’re developing the user manual for a car. You go down deep into the assembly plant, walk along the vast assembly line, and ask the big, burly factory worker, the one who tightens the bolts on the engine, “Hey there – do you know how the radio works? And what sort of person typically drives this car?” You won’t exactly get warm responses, or even accurate ones. This is because it is not the job of the assembly worker to know these things. They just have to know how to put the cars together so that they won’t fall apart or explode too much when you drive them. (Ford and GM notwithstanding.)

Conversely, can you imagine asking a car salesperson how much torque should be applied to the engine bolt to tighten it? Again, that is not their job to know. Recognize that subject matter experts (SMEs) are on a spectrum, from the most removed from the end user (developers), to less removed from the end user (QA testers, technical writers) to those in direct contact with end users (product mangers, business analysts, salespeople, technical support.) They are all various parts of the food chain, like amoebas, snakes, leprechauns and other creatures.

Therefore, when asking questions of SMEs, ensure the questions are relevant and appropriate. For example, I would expect the developer who created the multiple N-up printing field (the one that allows you to print several smaller images of pages onto a single page so that you use less paper), to know how it works, and the mechanics of it. I would not expect them to know specifically why a user would use it, or that the user should use larger fonts to make the printouts more legible. However, I would expect the product manager or business analyst to know why ths field would be used.

The challenge when conducting interviews is to find out the ultimate, true reason for a procedure, element or thing. Therefore, your questions must match the SME.

2. Know thyself - know what I mean?

Everyone is like a computer program: they are hard-coded with certain likes, dislikes and personality traits. They blossom in some environments and wither in others. It is therefore absolutely critical that you know the contents of your "program", so that you can recognize if it is compatible with the job you are applying for.

Just as you have a unique personality, the job you're applying for has one too. It has strengths, weaknesses, skills and other characteristics. If you don’t know yourself, how can you know if you’d be a good match for the job?

Why We Write

One of the questions you may be asked in an interview that will quickly indicate if you know yourself is: Why are you a technical writer? I’ve been asked this, and have asked it of candidates I've interviewed. You need to know the ultimate reasons why you're a writer, and it’s not enough to say it’s because you like working with documentation - that’s obvious. Why do you like working with documentation? Is it because you like helping others? Is it because you enjoy making order out of chaos? Is it because you're an end user yourself and get frustrated when you encounter a guide that is incomplete? Is it because your parents used to beat you with dictionaries? Know yourself to know these reasons.

The ultimate question where you must know yourself, is Tell me about yourself. Because this is such an open-ended question, most people dread being asked it. It is not an opportunity to spout your life story. The question really means: "Tell me about yourself in relation to this job, what you’ve done, what you’re doing now and what you hope to do, to show me that you’d be the best person for this position.” You must practice your response to this question. It may be something like:

"I’ve been a technical writer for over 10 years. I work mostly in FrameMaker, WebWorks Publisher and Adobe Acrobat, to create a wide variety of documentation including user guides, online help, technical guides and Release Notes. I like doing what I do because I enjoy the entire process of gathering and organizing information from a wide variety of sources, and putting all this into a guide that people can actually use. Finally, I’m very much a believer in content management so I’ve been studying it quite a bit, especially XML and DITA, and hope some day to work with these areas."

Other questions you may be asked where you really have to know yourself and why you do what you do include:

Name three things you like about technical writing. Have a list prepared!

What are your greatest strengths? – Are you a good multi-tasker? Are you persistent? Do you have good interviewing skills? If so, say so, and give examples.

What is your biggest weakness? State a weakness and show how you overcame it. For example, you may say you find it stressful rushing a project, so you have developed a good system of creating a doc plan with tasks and dates, and ensuring everyone follows it to avoid a rush.

Why are you interested in this position? You can only answer this if you know yourself, skills the job, and the company to show that there’s a match.

Passionate Documents

It’s important to know yourself and exactly why you’re a tech writer because this will help motivate you when gathering information for your docs. One of your ultimate passions should be to help – change won’t happen unless you are passionate about it. You need to be as passionate as the followers of Obama, and say:

Yes we can – create great documents.
Yes we can – convince management that documentation is important
Yes we can – convert all our docs to XML

Because we are the track changes we believe in.

Andrew Brooke - abrooke@primus.ca

Read More

Labels and other dogs

Here I am, in my basement, surrounded by mountains of dog food I'm desperately trying to organize. We own one dog, an odd-looking labradoodle named Jessie, however, my brother-in-law's dog Gracie often visits. Both dogs need feeding, therefore I own two large plastic containers filled with food for each dog, and both dog food types look almost identical. I wonder: What is the best way to label each container?

The obvious labels would be Jessie and Gracie, however I often get the dogs' names mixed up even when I'm around them; Jessie and Gracie simply sound too similar, and the dogs themselves do not carry signs that clearly identify them. I decide on the labels Our dog and David's dog, eliminating all confusion.

Labels are everywhere in documentation, specifically in:

• the name of a document: User Guide, Admin Guide, Install Guide, and so on
• chapter names
• heading titles

These are all critical identifiers, and just like the dog food box labels, they need to be clear, descriptive, as short as possible, and leave no room for confusion.

As an example, our company used to create Installation Guides, but this was not descriptive enough because it did not distinguish between guides for users who were installing our software for the first time, and guides for users who were upgrading an existing version. We therefore changed the document titles to:

• Guide for New Installations
• Upgrade Guide

Chapter titles and headings also need to be clear and unambiguous. Documents is vague, Creating Documents is better, and Creating Documents on a Database may be better still, especially if you need to distinguish between this topic and creating documents in another location.

Labels are also in software in the form of fields, menus and title bars. Experienced technical communicators provide valuable feedback and insight for the naming of these items. As with documentation labels, software labels need to be clear, consistent and leave no room for confusion.

I'll share an interesting example.

I was working with a developer on a complex database administration application. One of the functions the user could do was rerun a query by clicking a button labeled, appropriately enough, Rerun query. The developer said the problem was that there were many different queries that the user could run, and that they needed a quick way to know which one they had run before re-running it. I asked if was possible to embed the name of the query that had just run into the button name, so that, for example, if the user had run the Last Name query, the button label would be Rerun Last Name query?

I remember the developer's eyes widening and his face lighting up as recognized the elegant beauty of this solution. "Yes," he said, "it can be done!"

More exotic things I have be asked to label include database tables, attributes and elements. It can be very challenging, and very rewarding to give these things the right name, one that nearly sums up the essence of what the thing is. So choose your labels carefully - they can turn good documentation into great.

Now excuse me while I go feed the dogs...

Read More

Putting out fire with (pricey) gasoline

It's not a fun time to be a driver, especially if your car is anything larger than a phone booth. Gas is now almost $1.30 a litre. Creative thieves don't even bother trying to pry open locked gas caps - they simply get underneath your car, drill a hole in the gas tank and collect the liquid gold. Be glad you're not living in Britain, where the price per litre is an astonishing $2.40, almost double what we pay here.

The really sad part is that the price increases will continue. Within a few years, we'll match and then exceed Britain's current prices, and wax nostalgic over the days of $1.40 "cheap" gas. Can anything good come of this?

Hummers for sale

Yes, and it already has. People are forgoing their trucks, SUVs, minivans and other gas-guzzlers in favour of smaller cars. They are carpooling, taking public transit, and thinking twice before driving unnecessarily. High gas prices have become a de facto carbon tax, without all the messy legislation required. They are forcing people to be more environmentally responsible, and as Martha Stewart would say, "that's a good thing". High prices will no doubt accelerate the development and acceptance of fully electric cars. In other words, high gas prices are completely changing both society and industry.

Finger lickin' docs

Corporate change as a result of external factors and customer demand is nothing new. Recently, Kentucky Fried Chicken (KFC) announced changes that would make it more "animal friendly", as a result of pressure from the animal rights group PETA. (Veggie chicken burger, anyone?) KFC didn't do this out of the goodness of their heart - do you really think they care about chickens? KFC, like all corporations, cares about one thing - profits. And their profits have been dropping steadily as people try to eat more healthily. The last thing they needed was further criticism, so they gave in to PETA's demands.

A similar sea change is happening with documentation, but it will accelerate only when, as with gas, the price of the status quo becomes too high. For too long, companies have gotten away with creating documentation in an inefficient, unstructured format. They've been able to do this because they could afford to do it, but soon they won't be.

The ultimate 'change order'

The changes are already happening. The first companies to change were the ones where the documentation is translated into other languages. Translation costs are extremely high, but in an XML-based content management system, only the specific sections of text that have changed need to be translated. If a text segment is reused, so is its translation. The savings can be astronomical.

Companies with large volumes of documentation, often with different versions, also are changing to the new ways. Development time for new manuals will be shortened from months to weeks, or even days.

After all these international and larger companies have changed, the others will follow. They simply will not be able to compete otherwise.

Organizations have converted their documentation to the new format are reaping the rewards. Organizations that resist this change, that deny it's happening or that continually stall will end up in the same place as General Motors and Ford. Their documentation will explode more violently than a hundred litres of that pricey gasoline.

Read More

Documenting Brenda Martin

The saga of Brenda Martin has finally drawn to a close, for now. Imprisoned in Mexico for over two years in deplorable conditions, found guilty only in the last week of her imprisonment, she was transferred to a Canadian village prison, then quickly paroled. In an interview, she said she'd like to start her catering business again. I doubt Mexican food is on the menu.

Death by docs

There were two documents that destroyed Martin. The first was the indictment written by the prosecution, alleging she was guilty of money laundering. The second was the written verdict from the judge who found her guilty. Martin has claimed that portions of the second document were simply "cut and pasted" from the first. This is what’s known as “single-source justice”.

In addition to these two, there was other documentation that prolonged the agony after she was found guilty. The first was all the paperwork that had to be completed by Corrections Canada to arrange her transfer to a Canadian prison. This may have delayed her release a week. (Couldn't they have transferred her and then filled out the forms?) Once in a Canadian prison, under much better conditions, more documentation had to be completed to arrange her parole. Still, as documentation deadlines go, these projects were completed relatively quickly.

I'm not opinionated - just always right

There was a huge variety of opinions on this case, ranging from "she's innocent, let her out," to "she's guilty, let her rot." It seems likely that she was an innocent victim, who, at worst, showed poor judgment remaining in a foreign country that has a notorious justice system, after her boss was convicted of a major crime, and without a work permit. However, the hard truth is that none of us outside observers know for certain if she was guilty or not. We don't have all the information, only selected bits of it.

Ignorance ≠ bliss

Ignorance of the facts is one of the main causes of poor documentation. How often do we document something, or rely on others to supply us information for our docs, without investigating and testing it for ourselves? Thinking you know something is not the same as actually knowing it. Trusting is ideal; verification is the real deal.

Squeaky Gonzales

One point many people raised is that Martin was one of hundreds of Canadians trapped in foreign jails. Why did she get special treatment? Simply, it was her pure, visceral, and extremely emotional pleas for help that ensured she would be speedily rescued. The squeaky wheel gets liberated, and the squeaky workers get their way.

All companies have limited time, money, and resources. The job that gets done, including documentation, is the one where the "squeakers" push it though. The best documentation is created by the squeaky writers - the ones that push, plead, prod, persuade, probe, and pester until they get the tools and time they need to do their job and the answers they need to create great documentation.

A brief word on briefs

I've a feeling we'll be seeing more “Brenda Martin” documentation soon, specifically the legal brief her lawyer will file if she decides to sue the Canadian government for failing to help her sooner. She may also decide to appeal her conviction to the necessary legal body, although it's not entirely clear who that would be. Is there a World Court of Appeal?

If she does make either of these legal challenges, it raises an obvious question: what's the point? She's out of prison now, so why expend time, energy, and money to sue the government or clear her name?

Of the two legal challenges, clearing her name might be the more justifiable. She is a convicted criminal. If she truly is innocent, you could see why she would want the conviction expunged from her record. Convicted criminals have a tough time getting a job, however, most potential employers and clients would be quite sympathetic toward her. It’s doubtful the "criminal" lable would have any real effect.

As for suing the Canadian government because they didn't help her sooner, this could easily turn public opinion against her (there was already a "Brenda backlash" while her case was dragging on) as people simply perceive her as a gold-digger. I'm sure she could make plenty of money documenting her story into a book, which of course she could sell the movie rights to. It'll be a great CBC movie of the week.

Justify my docs

Just as it's fair game to ask what the ultimate purpose of these legal actions is, it's also fair game to be continually asking what the ultimate purpose of your documentation is. If you cannot justify the presence of certain text or sections in your document, then you must change or remove them. And if you cannot justify the entire document, it must be thrown on the scrapheap of all dead documents.

Ultimately, we and our work are all judged. This is especially true during a job interview. Are you ready to face the court?

Read More