Where do technical writers get information from? A typical tech writer task is documenting a piece of software. Often, there will be some sort of existing document that describes the software’s operation: training materials, design documents, even marketing materials. But eventually the writer is faced with the fact that at least some of the information they need is available in only one place: the inside of someone else’s head.

After all, that’s why it’s impossible for any automated design extraction tool to fully document the inside of a piece of software: much of the information about what the software actually does is held only in the designer’s head (and sometimes, it must be said, only in the designer’s dreams!).

So getting information out of other people is a key tech writer skill. Within the documentation industry this is called getting information “by interview”. This article gives some tips that you might find useful.

1. Listen

You have to actually listen. There’s no point in getting someone to give you a rundown on a particular software function, and then by your next question show that you haven’t actually listened to a word they said.

That’s one good reason why the use of a tape recorder is inefficient: the temptation is to not listen, let it go onto the tape and worry about it later. Another problem with tape recorders is that they (at least) double the amount of your time involved in the interview: you have to listen to the tape when you get back to your office.

If you take notes (and you should) this will be proof to the SME that you’re listening.

2. Understand

There’s no point in getting information out of someone if you don’t understand it well enough to be able to write about it. If you’ve missed something, or they use a term you’re not familiar with, stop them and ask.

Of course, if you’re completely in the dark about the software, or the domain it operates in, or software development in general, you’re going to have to ask more questions. That’s why people with technical backgrounds can work better with technical SMEs.

3. Don’t talk too much

Many technical writers are born communicators – that’s why they enjoy the job. Many born communicators just don’t know when to shut up. Of course, it’s absolutely necessary to ask questions, and to use reflective terms like “yes” and “right” every so often, but don’t start by telling the interviewee your life story.

4. Be sensitive about documentation

Software developers are always sensitive about a lack of design documentation for their products (as they should be). Don’t walk in, sit down, and say “Okay, where’s your design documentation?”. Try: “I suppose you haven’t had time to develop much in the way of formal documentation for this product yet?”

Many developers have only ever seen a complete set of ‘waterfall’ design documentation at university. Reassure them that you’ve seen bigger lumps of code with less documentation plenty of times.

5. Be sensitive about design

It’s easy to be critical about software design and ergonomics – but remember that it’s also easy to be critical about writing style and layout. If you’re in the middle of documenting a piece of software the last thing you need are user interface changes, so don’t suggest any. Write them down and hand them in when you’re finished, for inclusion in version 1.1 of the code.

6. Tell them how long you need

Salespeople making appointments will tell a potential client that they need 15 or 20 minutes of their time, knowing that if the client is interested, going beyond 20 minutes on the day won’t be a problem. You can’t afford to do that – you’re not there to grab the interest of the SME, and if you tell them you’ll need 20 minutes they’ll find they have something else to do after 25. Be honest, tell them what you want, and how long it will take: “I need to go through screens A, B and C with you, and it should take us no more than an hour.”

Also, try to ‘bunch’ your interviews. Rather than take 5 minutes of an SME’s time at odd moments through the day when you meet them in a corridor, make an appointment for an hour during the week, and keep all of your questions written down till then.

7. Keep on track

The SME doesn’t want to hear your life story – you shouldn’t have to listen to theirs, either. Or if you do, do it at the pub after work. Just remind them why you’re there. Try: “Look, I don’t want to waste your time, so can we get back to screen A?”

8. Do your homework

Let’s say for example you’re trying to work out what a bunch of screen prompts mean. Rather than sit down with a blank sheet of paper and a screen dump, make up a table of the prompts, and fill in (guess) all of the ones that you can. That way, when you get into the interview, the SME can simply check your guesses, correct the ones you got wrong, then tell you about the blanks.

9. Plead, cajole, threaten

Some developers simply don’t want to give you any information. This is often the case where there’s a maintenance programmer who is the last living expert on a particular critical application, and feel (perhaps rightly) that by telling you what they know they’re making themselves dispensable. There is no single answer to this problem, because people are all different. But sometimes it’s necessary to remind a SME that: there’s more to life than what they’re doing now (lots of new technologies they could be getting into, if only they could be free of their current responsibilities) their jobs are on the line if they don’t tell you what you need to know now (use this one with great caution, and only in extremis) your job is on the line if they don’t tell you what you need to know they can only serve the common good by giving up what they know

This is one of the toughest situations for a technical writer to find themselves in. Don’t be afraid to call in help from your boss, or the SME’s boss.

10. Have fun

SMEs are much more likely to want to spend time with you if you look like you’re having fun. Technical writing is fun (isn’t it?), so enjoy yourself.