Technical writing/Research

How to edit Wiki

Generally speaking, there are a limited number of approaches to getting cooperation and information from specialists:

The B's of interacting with SMEs

Subject Matter Experts (SMEs) have information. Your job as a technical writer is to transfer that information to other people. First you'll have to learn what they know. This is crucial to your success, so you have to know how to get along with these experts.

The Six Bs of SME Interviews

Bullying

Bullying developers is unlikely to be effective. In relative terms, they have more organizational power than technical writers and can resist this bullying very easily. In practical terms they have the information, and we need it. So what can we threaten anyone with? Very little. Don't try to bully SMEs.

Begging

Begging might work, but it's undignified. "Please, please tell me!" won't get you very far.

Bothering

Bothering developers is probably the most common and most annoying technique. A barrage of emails and reminders will eventually work, but you'll get the minimum amount of cooperation just to get rid of your pestering.

Bribing

Bribing developers can be the first step on the road to a longlasting friendship. Bribing in this context is giving the developer something tangible in return for their intangible knowledge, whether that be some chocolate or something larger.

Backscratching

The phrase "you scratch my back, I'll scratch yours" is a very useful motto for getting information from a developer. Backscratching is one step up from bribery as there is reciprocation between the technical writer and the developer.

The developer can be convinced with the reasoning that the technical writer is helping the developer by taking away the laborious task of writing documentation.

Befriending

The best way to get information from a developer is to develop a friendship with them. It is far easier to get information from your friends than it is from just another colleague, also your friends are far more patient of your misunderstandings.

Researching and Interviewing

Why Research for an Interview?

While it is true that the purpose of an interview is to gather information about the product you are writing about, it is also important that you take time to prepare before meeting with the SME.

One of the most important reasons for being properly prepared for an interview is to maintain your credibility with the SME - credibility in the eyes of a developer is of vital importance because if they have little or no respect for you then you will get the minimum of co-operation.

It is important when dealing with an SME not to attempt to bluff them and appear more knowledgeable than you really are, again it is vital to remember that an expert can spot a fake from a mile away.

Tools to use

There are many places we can look to in order to prepare ourselves for the interview.

The first place we can go to in order to find information is any previous product documentation which is available. This is important to be aware of because we do not want to ask developers dumb questions which have already been answered elsewhere. It can also provide useful information in the situation where we are writing about an update or amendment to a product as we can simply ask if the situation is still the same.

One of the most valuable tools for background reading is of course the Internet, in particular sites such as Wikipedia and Google. These sites are a gateway to background information which often the developer will assume you already know. So, be prepared for the developers' expectations and meet them.

When you are preparing software-related documentation, one of the most useful preparation techniques is to use the software itself, assuming of course it is available to you. By experimenting it is possible to formulate a reasonable assumption about how something works.

Know your SME

The SMEs we are most likely to come across when writing our documentation can be described using Alan Cooper's term "Homo Logicus", the following are typical traits of such a person:

Intellectually competitive
Trade simplicity for control
Enjoy mastering complexity
Often contemptuous of “users”
Lose sight of big picture

Tips for collecting information from SMEs

Don’t send e-mails asking for technical explanations. Either call the SME or go over to his or her cube and ask a few questions.

Set up official meetings with SMEs to ask all the questions you have. People may be busy, but they can rarely escape an official meeting if you set it up.

If you can sit near an SME, one technique that works well is to wait until you see them entering a "dead" state (e.g., they’re waiting for something to install, or they can’t figure something out, or they’re finished with something). Timing is everything. Ask a question at that time, and then ask another. It might get them going on a bit longer than they had planned.

Ask to look over their shoulder and watch what they’re doing. I suspect that many SMEs relish their techie knowledge, and this is one way to ingratiate yourself by inundating their senses with indirect adulation.

To get an SME to review a document, set a due date and call a meeting at which the SME is required to deliver his or her review. If you just send the document and ask for a critique/review, it may never come.

Although you can always buy an SME lunch, it’s sometimes hard to keep the focus on work. If you carpool, you can ask the SME questions in the car, where he or she doesn't have access to a computer.

Taken from I'd Rather be Writing by Tom Johnson, used with permission.

Conducting SME interviews

Remember this phrase when interviewing an SME: Proper Preparation Prevents Poor Performance

Resources

As well as being prepared in terms of background reading for the interview, it is also vital to pay attention to what things you need with you in order to successfully complete the interview.

Most important is how you intend to record the information you receive from the SME. Will you be writing? If so, do you intend to type straight to your laptop, or use a notepad and pen? If you are using the latter, is it a suitable medium for the location of the interview? If you are using paper and pen, it is always a good idea to have different colour pens available for highlighting information or separating the text clearly.

If you are not planning to write in situ, then bring a recording device to keep a record of the information that the SME presents. If the SME uses a whiteboard for diagrams, then have a camera with you to take pictures of the diagrams.

Manner

The where, when and how of interviewing is also very important.

Where

One of the key considerations when interviewing an SME is where you intend to meet to collect the information you need. This will of course affect how you record the information you collect, especially if you are meeting within a server room where a Dictaphone would be useless. The best option is, of course, a meeting room where the SME can bring a laptop to show you the information. This will also eliminate potential disruptions that can take place in the SME's regular work location.

When

Developers are busy people, so it is important not to take up their time for hours on end. By preparing properly for the interview, the technical writer can minimize the amount of time taken out of the SME's schedule. Ideally, the maximum duration of an interview should be about an hour.

How

When interviewing an SME in a meeting room it is a very good idea to create an atmosphere that is conducive to your task, which is getting information. A developer's natural environment is not an office, it is the server room, so it is necessary to be relaxed, and it is always a good idea to have coffee and biscuits or chocolate available.

It is also important to consider how you plan to talk to the developer, "register" is vitally important as we neither want to be overly familiar or overly formal with the SME. Learn their language and speak to them in terms they understand.

Information Chunks

Everyone makes assumptions, and developers are no different - they will assume that you have some background knowledge on the product about which you are writing. So, it is important to not ask broad sweeping questions, but rather questions that require an individual "chunk" Technical_writing_structure of information.

Good technical writing presents information a chunk at a time, so your questions should reflect this reality and look only for chunks that are useful, rather than writing monologues. We are writing about how something works, not the Queen Mab speech from Romeo and Juliet.

Preparation

Remember the phrase: Proper Preparation Prevents Poor Performance

At this point the tracking procedure begins. It is important to keep the requirements specification of the project in mind so that the information you acquire is in line with that specification.

It is important to have clear and well-defined questions ready; always be focused and ask open questions rather than closed questions that expect a "yes" or "no" answer.

Make sure any equipment that you are using works.

Beginning

Always be prompt, there is nothing more annoying for a busy developer than someone being late.
Thank the SME for his or her time.
Inform the SME of the scope of the interview and why you need the information.

Conducting

Taking notes is important. Pay particular attention to concepts, numbers and relevant facts. There is no need, however, to copy the SME's answers verbatim.

Begin with the questions you already have so that you cover everything in the plan.

Ask follow-up questions in order to clarify the SME's replies or to get extra information that is useful for you.

Bring the SME back to the points you want covered, don't be afraid to lead the interview rather than simply letting the SME waffle all over the place.

Finishing

When finishing the interview it is important to check that all the questions you have prepared are answered. This is an important part of the tracking process.

Ask if there is anything you have overlooked.

Thank the SME again for his or her time.

After

Validate the information you have acquired.

Tracking a task

Keeping a track of your work is essential for the life cycle of a project. If you don't keep track, then how do you expect to know what has been done and what needs to be done?

Make a list of topics and concepts that correspond to the requirement specification of the system. By tracking these requirements to the actual system and documents delivered to the users, you can validate that you've covered everything.

What is Validation?

Once you have interviewed the SME and created your documentation based on the information chunks that you have gathered it is important to validate that information.

Validation is a process that ensures that the information you have written is accurate and, most importantly, that it works.

How to Validate

Providing accurate information is one of the most important tasks in technical writing.

The first line of validation is, naturally, self-validation. This is particularly true when you are writing documentation for software that you have access to and are able to test the information in the software environment first hand.

It is also a good idea to consult a fellow technical writer, remember that no one person knows everything there is to know about writing documentation. A second set of eyes may notice things that have slipped through undetected because of your familiarity with the text.

Having the SME validate your work is also a useful approach. This is especially true in our situation where the SME is practically the same as our target audience. However, in more general technical writing this approach can be detrimental to the process of writing for the target audience. The developer is a key resource for validating the veracity of what is written, but never for commenting on the style.

Learn More

back to Technical Writing Level 1