Ask Nicely and Ye Shall be Informed

By Edwin Skau

(Note: this article is intended primarily for technical writers from the software domain.)

Many technical writers feel that the most difficult part of their job involves getting useful inputs for their documents from subject matter experts (SME). Unfortunately, gathering information from SMEs (usually programmers), however difficult, is an integral and critical part of a technical writer’s job. Writers and programmers have their own sets of grouses and issues with the interaction, based on their diametric perspectives. This is, however, more of our problem, because the results of these interactions are critical to our work.

Some organizations have a formal information gathering system that may involve including such responsibilities into an SME’s task list, and providing a standard format for inputs. Formal systems, however, often draw grudging compliance, and like most “compliance-driven” activities, end up providing unsatisfactory output. There’s a point beyond which procedures and policy do not deliver. It makes a lot more sense to personally cultivate your sources and establish active channels of communication.

Here are some tips to help improve your interviewing experience. Use them as you see fit.

1. Do your homework. Nobody questions, especially open-ended ones. Programmers hate being the victims of a trawling operation. They do not feel responsible for educating you on information you should know in order to do your job. Like you, they too have deadlines to meet. Their output is (usually) tested more rigorously than yours. Respect their time, protect your reputation. Do your homework.

• Read up all possible material on the technology, the product, the market for your product, and your company’s marketing plan for the product.

• Attend all meetings where you can interact with the project team members, and participate in their discussion.

2. Plan your information outline. Create an information outline for each of your documents. Consider each topic and draw up questions to answer each gap in your understanding. What you need to know usually maps to one of these questions:

• What is it?

• What does it do?

• How does it do it?

• What does it need to have in place to do this (dependencies)?

• What are possible issues I could face with this? And what are possible workarounds?

• Why will our customers want/need to do this?

Select examples that illustrate your queries better.

3. Identify your resource. Pick the right person to answer your questions. We often get ambiguous responses from people who are not the proper authority on a topic. Some people will not admit to ignorance. Others will just pass the buck, to let someone else handle the “extra work”.

4. Schedule an appointment. Meet and discuss your information needs. Inform them of your requirement, provide context, and explain how important it is to your work. List the areas in which you think this person can help you, and ask whether they have some material they’d like you to read up before you meet.

• Choose a place for your interview according to the kind of information you will require (your workstation, the SME’s workstation, a conference room, or other common work area). It’s always a good idea to have a white board or lots of rough paper at the venue.

• Fix up a time for the interview. The best way to go about this is to propose a time, or ask for a time within a given timeframe.

• Put the venue, time, and scope of interview in a mail and send it to the SME. Copy both supervisors (yours and the SME’s) on the mail so that they can schedule their work with you around this appointment. Include a list of topics you would cover in the interview.

• Remind the SME a short while before the interview, to ensure they are free and in the right frame of mind to be useful.

5. Conduct the interview efficiently. The best way to get people to respect your time is to respect theirs first.

• Ask clear, specific questions. Provide a context for your question, and ask them to confirm what you know about the topic.

• Pay attention. You asked a question, now listen to the answer. Sometimes it helps to repeat the answer or paraphrase it, to get it down right. Take notes.

• Ask for clarification. If there is something you didn’t quite understand right or are not fully satisfied with the answer, ask more pointed questions. Or ask for more reference material and someone else in the team who could give you a slightly different perspective on the topic. Do not leave until you have answers or a further plan for all your topics.

• Thank them for their time and effort.

6. Follow up. Send the SME a summary of the interview to ensure that your understanding on the topic matches theirs.

• Make your gratitude public. Let your SME’s supervisor know how helpful the inputs have been. Create a list of contributors and publish that on your intranet or save it in your project records.

In short: be precise, be brief, be smart, and be grateful. That will help you on your way to ultimate success.

Edwin Skau is an independent management consultant whose services include setting up and re-skilling documentation teams for software companies.

To contribute to this column, contact the column editor, Ramesh Aiyyangar.