Technical writing/Researching and interviewing EE

From Wikiversity
Jump to navigation Jump to search

How to edit Wiki

Wikiversity Main Page

back to Technical Writing Level 1

Researching and Interviewing[edit | edit source]

There are a limited number of opportunities to get cooperation and information from experts: The experts are people who have the best information about the product, but the experts are the busiest people on the project. It is important to minimize interview time and allow them to develop the product or project. Do not waste the expert's time. The better prepared for the interview you are the less time the interview will take.

Plan the Interview[edit | edit source]

Review notes from the project manager. Focus on the subjects that you have agreed to write about. Read any previous product documentation on the subject matter. This research can provide useful information. If writing an update or amendment to a product, ask which information has changed and which information is still the same.

  • Book a quiet room so you can hear everything the expert says.
  • Officially invite the expert to the meeting (they are more likely to come).
  • Be sure of what subjects must be covered.
  • write a list of open questions (questions that cannot be answered yes or no)
  • research the subject matter, the research will make your questions more specific
  • do proper time management

Prepare for Interview[edit | edit source]

  • bring everything you need to the interview, pens, paper, computer notebook
  • choose a quiet place for the interview
  • choose a convenient time for the interview

Conduct the interview[edit | edit source]

  • arrive at the correct time or before
  • thank the expert for their time
  • ask all the questions on the list using open questions

Validate the information after the interview[edit | edit source]

Check the information you record and ensure that it does not contradict other previous information

  • track each task (every update or amendment)

Why Plan the interview?[edit | edit source]

Testers, developers and architects are busy people.

Minimize the amount of time spent.

The maximum duration of an interview should be 30 minutes.

Remember the phrase: Proper Preparation and Planning Prevents Poor Performance

How do you prepare for an interview?[edit | edit source]

It is important to prepare clear and well-defined questions.

Always be focused and ask open questions.

An open question is a question that you cannot answer yes or no to.

Make sure any equipment used works before the interview.

Why Research for an Interview?[edit | edit source]

It is important to prepare before meeting with the Subject Matter Expert. (SME) This:

  • reduces the time that the interview lasts
  • assures the SME that they need not explain everything from basic principles.

When the research is complete some information may require explanation.

Write a list of questions to ask the SME.

The aim is to get all the information needed in one interview.

What to bring to the interview?[edit | edit source]

Bring:

  • a laptop or tablet to type the information directly into the document
  • a notepad and pen to note phone numbers and the names of other SMEs
  • different coloured pens to highlight information or separate the text clearly.
  • a recorder to record the information that the SME gives verbally.
  • a camera to take pictures of any diagrams the SME draws on a whiteboard
  • a copy of the old version of the document or any research material used.

Where is the best place to have the interview?[edit | edit source]

Always book a quiet meeting room where the SME can bring a laptop to show you the information.

SMEs will attend most booked meetings

Do not book a meeting in a cafe or noisy environment.

This will also eliminate potential disruptions that can take place in the SME's regular work location

When is the best time to have the interview?[edit | edit source]

The best time to have an interview is when the SME has time.

If the SME has an assistant ask when the SME is likely to have time and book a meeting then.

Monday mornings are usually the worst time because many issues arise over the weekend and often on Friday afternoons the SME will finish off the tasks for that week.

How do you start the interview?[edit | edit source]

  • Be prompt
  • Thank the SME for his or her time
  • Tell the SME:
    • the scope of the interview
    • why you need the information

Conduct the interview[edit | edit source]

Do not record every word that the SME says

  • Take notes of:
    • concepts
    • numbers
    • relevant facts.
  • Begin with prepared questions
  • Ask more questions to clarify the SME's answers
  • Do not be afraid to lead the interview
  • Return the SME back to the points where the answer does not completely clarify an issue
  • Check that all the prepared questions have answers. This is an important part of the tracking process.
  • Ask if anything was overlooked.
  • Thank the SME again for his or her time.

Validate the information after the interview[edit | edit source]

Validate the information acquired by checking that the information does not contradict another source of information. If there are contradictions prepare a list of questions and book another interview

Track each task[edit | edit source]

Each update or amendment becomes a task.

It is essential to Track each task for the life cycle of a project. If tasks are tracked then everyone in the team knows:

  • what has been done
  • what still 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 this validates that every task has been done.

How to Validate[edit | edit source]

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

Test the information against the software if available.

A second technical writer notices errors undetected because familiarity with the text.

Let the SME validate information in the document. The developer is a key resource for validating the veracity of what is written, but never for commenting on the style.

Tips for collecting information from SMEs[edit | edit source]

  • Don’t send e-mails asking for technical explanations.

Either call the SME or go over to their desk 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.

A key tip to ensure that your work is reviewed on time and every time, is to confirm that the Development team or Product team takes ownership of the documentation deliverable as part of their product release. For documents that do not have to go out to a customer with the product, it is the responsibility of the writer and Development/Product Manager to block the SME time for review. No amount of reiteration can convince a SME to actually review the work unless there is a commitment from the Development or Product team to deliver a document on a said date and time. Use escalation and email reminders with prudence and be gentle in your communications.

End of lesson Test[edit | edit source]

  1. Where is the best place to have the interview? A quiet room where you can hear SME perfectly.
  2. When is the best time to have the interview? Where the SME has time but not on Monday morning because it is usually very busy and the SME will not pay much attention to your interview.
  3. How do you prepare for an interview? Book a quite room, write open quetions, get familiar with the subject, oficially invite the expert.
  4. How do you start the interview? Thank the SME for his/her time and inform him/her about the scope of the interview and why do you need the information.

Back to previous module[edit | edit source]

Personas (EE) How to use the correct language for the people who will read the documents

Forward to next module[edit | edit source]

Structuring Information(EE)

Learn More[edit | edit source]

back to Technical Writing Level 1