One of the crucial skills a technical writer should possess is knowing how to elicit information from subject-matter experts. And in terms of importance, this skill comes almost back-to-back to the actual ability to create a useful document. Without the data on the topic in question, you won’t be able to write a decent document. As simple as that.
In this article, I am talking about conducting an interview as a technical writer in the product software development environment. The process and peculiarities might differ in other areas, but I believe that the main principles are quite universal.
Do We Need Interviews at All?
Sometimes, challenges start to occur even before the interview has begun. Explaining the need for such a meeting can be demanding because a seasoned developer might tell you — the best documentation is the code. And certainly, it contains a grain of truth. Clean code with comprehensive comments along the way, what else can a fellow developer wish for? But there is a hint of utopia in this phrase because it sounds too good to be true. Not always, but often enough. Here are some proving points:
- Humans are not perfect, so is the code they write. The coding skills as well as a hanker for writing comments might widely vary depending on a person.
- Enterprise-like environment. You can always rely on checking the code for better understanding how a certain functionality works. But what if you don’t have access to the repository because it is maintained by another team? This can easily happen in large companies with strict (and rightly so) data protection policies. To get to the code base, you need to request access, prove that you need it, etc, etc. A samurai has no goal — only a path.
- External communication. In case you provide external APIs for your software, well, the documentation is inevitably crucial.
I have established above that once in a while there can be cases where we need technical documentation. In terms of expertise level in software development, a technical writer is no match to a developer. Hence the need to conduct interviews with the representatives of the developing team: a developer, quality assurance engineer, or other roles, for example, a system architect or a system analyst. The better a technical writer is prepared for such an interview, the more useful the outcome will be.
How to Prepare for an Interview and Successfully Conduct it
The first and most important rule: you do not have to be a subject-matter expert, but understanding the field you work in is a must if you want to become an efficient interviewer. Constant learning will immensely help you increase the level of expertise needed for this challenging yet fascinating job.
The following pieces of advice are based on my personal experience. I developed them based on what can work best for the resulting document.
- Prepare for the interview. As in boxing, the easiest part of the training is the fight itself, the hardest and most important part is the preparation. The same principle applies here too. For the interview to turn out to be successful, you need to establish:
- Target audience.
- Which problem/s the resulting document will solve.
- Which format is needed: tool, language, level of detail.
- Schedule an interview in advance, and don’t skip the agenda. It doesn’t really matter where you write it: in the direct messages/email/calendar event description — the main goal is to make sure that the interviewee knows what you need from them. And that they have enough time to prepare for the interview. In case the time is not enough, it is ok for the interviewee to reschedule the meeting to have a bit more time to prepare.
- Record the meeting, and don’t forget to ask for permission first. During the interview, especially if the topic is complicated, it is possible not to grasp certain details, so the recording will help you revise the information and confirm in case there are doubts.
- Send the draft for review. The expert needs to check whether all the facts are presented correctly. Styling and formalization are not essential here at all, you just need to establish that the facts are correct.
- Receive a written (!) confirmation that the review is done, and the information in the draft is correct. This will be your starting point in the document polishing before handing it to the customer.
Challenges
Interviews are conducted in the corporate environment, where there should be an appropriate level of work ethic. But since you deal with people, not robots, certain cases might occur, where you need to adjust to the situation on the spot. Here are the examples of difficult interactions from my experience, and what solutions I have developed to make an interview a successful one.
- A “delegate” person. They do not want to make the slightest effort. Such a person might be lazy or value their time too much to answer your questions. They can say something like “you can read this article”, “go to that person for the details”, etc. It means that you are not receiving any actual answers to your questions. No worries, you can work with that, but you need to adjust a bit. If possible, check the documents they send right away during the meeting, to see whether they contain the needed information. If they don’t — ask questions to elicit lacking data. In case the documents are too big/complicated to read right away — highlight the fact that you will come with the follow-up questions. It might be a good motivation for this person to answer the question now and not spend time later, or at least you will be able to actually come with questions without it being an unpleasant surprise.
- A “yes/no” person. In case you are having an interview with someone who prefers to be concise and answer in short phrases, the first rule here — don’t take it personally. This person is not mean or rude, just less talkative. Usually, in such cases it is crucial to get your point across about the purpose of the document: it should be clear and precise. Here you can use active listening techniques and paraphrase the short answer with the intro “Did I understand you correctly that…”. It can motivate the person to add more details to your paraphrased answer.
- A “too busy” person. Being succinct in such cases is a skill to master, but don’t forget that you have scheduled this meeting, so you have this time to ask the questions you need answers for. If the person postpones the meeting several times, and you realize that it might affect the quality of the document due to the proximity of the deadline — don’t be afraid to escalate the issue to the customer of the task. It doesn’t have to be a dramatic rumble, of course, but sometimes the authority of the customer or a superior manager works wonders.
- A “too many details” person. When you talk to a true fan of the craft, you can be amazed by how easily such a person can be carried away and dig into too many details. It is the best sort of “challenge” a technical writer can have during the interview. You just need to navigate the meeting, agree on the level of detail for a particular document, so you would understand when to get back on track with the agenda of the meeting.
Conclusion
Talking to people in general might be challenging, talking to experts in a certain domain might be even more demanding.
It is essential to come to an interview well-prepared. You can even consider it a matter of good manners and corporate etiquette. Knowing at least the main gist of the topic to be discussed and having a list of questions will speed up the process and make the entire conversation more efficient.
Remember that there is an actual person in front of you in a meeting room or a Google Meet conference, not a tag in Slack or a username in Gitlab. Any person has their style of communication. Adjusting to this style is the key to success.
