New Technical Writer Avoiding The Interview Writing Disconnect

New Technical Writer: Avoiding The Interview-writing Disconnect

OVERVIEW

Lost or garbled information is a terrible waste. Especially if it's the information you gathered from an interview and must now write into your User Document. Here's how to prevent that waste.

THE SITUATION

You had an interview with a Subject Matter Expert (SME, someone who has the information that you need) for your product. He/she told you all that you needed to know. However, by the time you got to write the material into the User Document, you have forgotten much of what was discussed. Your notes only help a bit. This loss or garbling the information from the SME that you need for your writing is the "Interview-Writing Disconnect."

SOLUTION

The solution is divided into three components: Preparation Before the Interview, Actions During, and Following the Interview.

TIP: If possible, schedule the interview as close to the time that you are going to write that part of the User Document. The longer you wait between the interview and the writing, the more difficult it will be to recall the content.
Before the Interview

* Your guiding principle is to Be Prepared. You should have read what you can about the product, its environment, who will use it, and what they (usually) want to do with the product.
Know as much as you can before the interview. The more you know about the product, the better off you will be in the interview.

* Specify the goals of the interview. Share this information with the SME. Do this in an e-mail before the interview.

* Ask the SME if you can (audio; video is too obtrusive) record the interview. Get a recorder (preferably a digital recorder) and make sure it is set up to function properly during the interview.

* Gather any other materials you will need for the interview.

* Set up your recorder, etc quickly when the meeting begins.

* (You might want to practice taking legible notes...I sure need to)

THE HARDEST PART

Leave your ego at the door. (This is really hard.) Don't make signs that indicate that you understand something that you do not. Ask questions, get the explanation that you need. Here is something to tell the SME:

"If I ask what sounds like a stupid question, bear in mind that I am acting based on the knowledge that our User has."

DURING THE INTERVIEW

Record the interview (if permitted).

Start with some overview questions, such as:

* What is this portion of the product (topic) called?

* How does this topic fit in to the product?

* What is this (portion of the product) used for?

* When would someone use this (unless it is "obvious")?

* What has to be set up before the User can use this part of the product?

* Any other conditions about when this would be used, or when it would be avoided?

After you have the background information, then move on to the actual operation of the part of the product. Ask any questions that you have prepared and any others that come up in the interview.

Remember, if you do not understand something, ask.

Ask some summary questions. Review the steps that you took, saying them out loud in your own words (especially if you are recording the session). Have the SME correct any mistakes that you make.

Ask if there is any related information to this topic. Are there any tips or traps using this part of the product?

MORE ABOUT RECORDING INFORMATION

If the SME points to a part of the product (such as a window in a piece of software, or the control panel of a barbecue) then say out loud what the SME is pointing to. Say something like "we are looking at the main address book window" or "we are looking at the main burner control." This will enable you to link what is happening in the interview with the audio tape.

If the SME performs an operation, say what it is. "You just entered the new person's name, and the 'New Card' window appeared." Or "You just turned the burner control to the 'Light' position, and now the igniter is clicking, and there's the flame."

Take notes as well as you can. But do not let any of your activity get in the way of the interview. It's not a good idea to keep stopping the SME while you catch up with your note taking. You will have the audio recording to fall back on.

The SME might provide handouts for the interview. If you are allowed to, take notes on the handouts. The goal is to link your audio recording and notes and handouts together. For example, if the SME provides a screen print for a software product, you should link your notes, audio recording and the handout together by reading the title of the handout aloud. Do it as unobtrusively as possible.

AFTER THE INTERVIEW

As soon as possible after the interview, you must go over your notes and handouts. If possible, this should be done within minutes of the end of the interview. Find a quiet place (perhaps you have access to the interview room after the interview) and go over your notes.

Review your notes and add clarification to them. When you add the material to the notes do it with enough detail so that someone who was not at the meeting will be able to understand it. That person is you in even a day or two!

As soon as you can get to it, take the expanded notes and write them into a draft of that part of the User Document. That should be within a day or two of the interview, if possible. Every minute's delay adds to the disconnect between what you learned in the meeting and what you write.

Let your draft sit for a day or so, then review and revise it for clarity and completeness. Consider sending the reviewed and revised version of the draft to the SME for comments. (You only want comments on the material, not on grammar.)

Schedule time for this writing, even if you are juggling several writing projects. The time you save in not having to recall the information at a later date will be a good investment.

THE BOTTOM LINE

You can avoid or reduce the effects of the Interview-Writing Disconnect by being prepared before the interview, asking questions and taking effective notes during the interview, and reviewing and writing the material as soon after the interview as possible.

BONUS : New Technical Writer: Don't Confuse Your Reader With Your Words

OVERVIEW

Stop confusing your Reader with the words you use. Your Reader is trying his/her best to understand how your product works without having to figure out your writing. Here are some writing guidelines to help you stop baffling your Reader.

SAME CONCEPT: SAME WORDS

User Documents are not meant to be entertaining. Do not try to be creative, especially by using synonyms for specific concepts in your product. When you talk about a topic use the exact same wording to describe (or name) the topic everywhere in your User Document.

For example, the "Same Concept: Same Words" guideline, says that if there is a control on your product called the "Activation Button," then everywhere you talk about that button use the term "Activation Button."

Don't be "creative" and use words like "Activation Control" or "Start Control" to refer to the "Activation Button." Using the different wordings forces your Reader to have to stop and think "Is this the same thing as 'Activation Button'?"

DIFFERENT CONCEPTS: DIFFERENT WORDS

I bought something on the Internet that had a rebate available for it. When I ordered the product, I was given a "Tracking Number" to monitor the progress of my order. This is common for orders from large companies.

When I applied for the rebate, the rebate company used the same word, "Tracking Number," but this time it meant "their rebate tracking number." When their website asked for "tracking number" I entered the only one that I knew, the product ordering tracking number. I was wrong; the rebate number was a totally different thing.

The Rebate number is different from the order tracking number and should have a very different name from the order tracking number.

One might argue that "the rebate company is a separate company, and must handle rebates for all sorts of sellers." Sure, but they can use a very specific name for their rebate tracking number. They can call it the "Rebate Identification Number." That name would not be used by any selling company to track an order. The problem is solved. No User would confuse "Tracking Number" with "Rebate Identification Number."

QUIZ

Given the information in the previous two sections of this Article, wouldn't it be really silly if the rebate company originally called it the "Rebate Identification Number" and then unannounced switched to calling it the "Rebate ID"? Answer: Yes, it would be very silly. The change forces the Reader to have to ask, "Is this the same thing as the 'Rebate Identification Number'?"

It's not that your Reader is too stupid or lazy to figure out what you mean. It's that your Reader has better things to do than to decipher your writing.

WORDS YOUR READER DOESN'T KNOW

Jargon is the shortcut language of any industry. Make sure that if you use jargon in your User Document, you explain what it means. If the writing project can afford the bit of time, I recommend that you include a glossary in your User Document. Define all the jargon, acronyms, and words that you might use in ways your Reader might not expect. A great example of the latter are "debit" and "credit." The common understanding of these words is exactly opposite to those in the accounting (banking) profession.

TIP: Be suspicious of any words your spelling checker identifies. Ask yourself two questions when your spelling checker identifies a misspelled word:

* Did I really spell that word incorrectly?

* If it's spelled correctly, am I certain that my Reader knows what the word (or acronym) means? If it's not in the spelling checker's dictionary it might not be in your Reader's vocabulary.

DON'T BE AMBIGUOUS

I have a notebook computer running MS Windows XP. If I am using the Media Player and I press the keys to hibernate the computer (put it into an energy-saving sleep state), something warns me that hibernating will lose my place in the video. It then asks: "Do you want to continue? Yes/No." Continue what?: Continue hibernating, or Continue watching the video? It would only take one or two more words to remove the ambiguity.

THE BOTTOM LINE

When you revise your writing, make sure that your Reader does not have to guess what a word might mean. If you mean the same thing as another concept, use the exact same name. If you mean something different, then use as different (unique) a name as you can. Define jargon, acronyms, and any unusually used words. Eliminate ambiguity.

Your reader is uncomfortable enough having to read your User Document, instead of using your product. Don't make things worse by using wording that makes your Reader have to work out its meaning.