Do you want to know how you can write about technical subjects that you haven’t studied? For example, you want to know how you can write a user manual about a software system when you haven’t studied programming or the job the software will be used to perform. How can you write an effective proposal to bid on a project when you aren’t experts in how the different tasks involved should be done?
These are valid questions, but the good news is that you don’t need to be an expert in a specific field to write about it. This article focuses on skills needed to be an effective technical writer. A technical writer must have research skills, question – asking skills, and analytic skills. Without these skills, technical writer’s efforts to gather information can be unfocused and erratic.
Gathering information may be the most difficult and time-consuming part of a technical writer’s work. The information you need in order to write your documentation will likely be scattered in many different places. Some of it may exist on paper or in computer files. You may have to look for it in computer source code. Much of what you will need, however, probably is in someone’s head and no one has ever written it down. Getting that information will be the most difficult of all. Good interviewing skills are essential.
To write your technical documents, you must find the information and sift relevant jewels of knowledge from much that is irrelevant. Ask your contact person at the company for names of people to use as subject matter experts. As soon as possible, introduce yourself to those people. Tell them who you are, what you will be doing, and who told you to contact them.
Do this for several reasons. For one, if they are not the correct people to talk to, you need to know it as soon as possible. Your contact at the company may be mistaken about this person’s ability to contribute to your documentation.
A second reason to contact subject matter experts early in the project is so they know you are a member of the team. Once they learn that you are writing the documentation, some people will shower you with information they think you need, thereby helping you write your documentation more quickly.
Third, by contacting your subject matter experts early, you get to know them and build rapport. If they know who you are, they will be more receptive to talking to you later.
In this Initial conversation, tell them how you plan to work with them. Emphasize that you will try to take as little of their time as possible.
Why is this important? Your subject matter experts are busy people. Explaining the product or application is something they have to addition to do in addition to their regular work. They may have worked with technical writers in the past that ran to them every time they had a question, or did not prepare for an interview by learning as much as possible on their own. If you let your subject matter experts know that you respect their time, they will be more likely to share information with you.
To get the information you need to write your documentation, ask questions. Sounds simple, right? After all, asking questions is one of the first communication skills you learned. Remember when you were a child and every few minutes you asked your mom or dad, “Why…?”
Actually, although asking questions may be natural, asking good questions is an art. Not every question is a good question.
Many people think that whoever is doing the most talking is the one who controls a conversation. Not true. The person who listens and asks questions is the one who is really in control. By the type of questions you ask, you can lead the conversation in the direction you want it to go.
However, if used incorrectly, questions can be annoying or even offensive. Think about people you have known who asked questions that made you feel uncomfortable, maybe even angry.
In today’s world, it is especially important to develop the ability to ask questions skillfully. You may deal with people from many different cultures. Are you aware that people from many non-western cultures consider some types of questions to be offensive or overly intrusive?
To learn how to ask good questions, let’s review the basics.
There are two kinds of questions – open-ended and closed-ended. People can’t answer open-ended questions with yes or no. Open-ended questions open up the dialogue because you probably don’t know the answer before you ask the question. As a rule, open-ended questions begin with the words “what”, “how”, “why”, or “could”.
Before we go any further, we need to look at questions that begin with “why” more closely. “Why” is a challenging word. It implies that you have made a judgment. “Why” questions top the list of ones that make people feels uncomfortable. If possible, begin questions with the word “why” only when you’re talking about neutral subjects, such as, “Why does the computer make that funny noise?” Avoid beginning questions about personal subjects with the word why. For example, asking “Why did you do that?” sounds very confrontational to some people. If you must begin a question with the word “why”, soften its impact by expressing acceptance before you ask the question. For example, you could say, “It’s obvious that you really worked hard to make this interface easy for the user to understand, I don’t understand one thing, though. Why didn’t you make the background green instead of blue?”
At the other end of the spectrum, “could” is an extremely versatile question-opener. The word “could” can preface open-ended or closed-ended questions. If you begin a question with the word “could”, the person you are interviewing feels that he or she is more in control of the conversation. For example, if you ask a subject matter expert, “Could you walk me through the process step-by-step?” he can answer, “No. We don’t have time right now,” without feeling as guilty as he might if you asked “Would you walk me through the process?” On the other hand, if he has the time, his response may be, “Certainly. I would be pleased to do so.” Whenever you use words that allow the other person to feel in control and can assure the other person that he or she can say no without guilt, you strengthen your bond with that person.
Here are some tips about how use different kinds of open-ended questions:
- Questions that start with the word “what” lead people to give factual answers. (“What happens next?” or “What do you do next?”)
- Questions that start with the word “how” lead people to discuss processes or sequences. (“How does this work with the existing system?”)
- Questions that start with the word “why” lead people to talk about reasons. (“Why did you do it that way?”)
Closed-ended questions are also useful when interviewing. These questions can have “yes” or “no” answers. You would use closed-ended questions to verify information, gain a commitment, or open up a conversation with someone who is uncomfortable. Closed-ended questions often begin with “is”, “are”, or “do”. Some examples are questions such as, “Is this the way to do this?” or “Are all of the components in the box?” or “Do you know how to configure this?”
If you’ve never interviewed a person before or you sense that a person is uncomfortable, start your interview with a simple yes-or-no question. This makes the other person feel in control and more confident. It also builds rapport and sends a message that you respect the other person’s feelings. A simple closed-ended question, such as, “Are you ready to start our interview?” can work wonders with a nervous or reluctant subject matter expert.
Sometimes questions don’t keep the interview moving. The person you are talking to isn’t cooperating and does not answer questions readily. You feel the interview coming to a halt. Now what do you do?
Situations like this can make you feel more than a little panicked. When this happens, it is time to ask another question. Make this one a little tougher than usual, maybe even challenging (without being hostile). Put the person into the question by asking something like, “Would you say, then, that the system interface is adequate for our users’ needs?” You have put the other person on the spot. He must say yes or no.
Sometimes, when people don’t want to cooperate with you, they will answer your question, but their answer won’t make sense. Perhaps they speak in generalities or use language you don’t understand.
If this happens, don’t let the other person off the hook. Listen to what this person says, then take a few moments to review your notes or collect your thoughts. Don’t worry about the silence. Silence is a powerful communication tool.
While you are thinking, frame your question and determine whether you need verification or a better explanation. If you need to verify that you understand what the person said, closed-ended questions work the best. If you ask, “So are you saying that this application interfaces with the user’s desktop?” the person can answer yes or no.
If you need a better explanation, say, “I’m not sure I understand what you mean. Could you explain that more?” This type of question can have a strong effect with uncooperative people. It gives them a sense of control, but it also demands an answer.
After you have conducted your interviews, you probably will have an abundance of information for your document. Some of it will be useful. Some will not be useful. There’s a good chance that you won’t have all of the information you want.
At this point, you may be confused about where to start. What do you do? How can you ever separate what you need from what you don’t need? This is the time to analyze what you have and how you are going to use it.
When you start analyzing your information, there is a good principle to keep in mind. It is called the KISS principle – Keep It Simple, Silly. If you refer to this principle often, it will remind you to keep your documentation as simple as possible.
However, don’t think that writing a simple document will make your job easier. In fact, be prepared for the reverse. It takes much more effort to write something simply than it does to write a long treatise on a subject.
Analyze information in the light of providing support for your readers. As a technical write, you can’t separate yourself from either the development or production worlds. To write effective technical documentation, you must keep in mind that your readers need useful documentation that gives them the information they need, written in clear, concise language.
When you analyze the information you have gathered, find ways to present it in a manner that builds your readers’ confidence. Detach yourself from the information and analyze it from the readers’ viewpoint.
Look for things that don’t make sense to you. If you don’t understand something, you can’t explain it to someone else.