What should technical writers ask analysts when writing technical documentation support materials for a product’s end users? Leading tech comms expert David Farbey looks at the right questions for analysts in the first of a three-part series on ‘What to ask…’ analysts, managers and engineers.
As a technical writer – of user guides, tutorials, online help systems, reference manuals, policy and procedure guides or other business document – you need to give your readers the answers they need so that they can use your company’s products to do their jobs. To get those answers, you need to ask the right questions of the right people. Easy, right?
Who to ask?
A typical product development team includes analysts and managers as well as engineers. We tend to group all these people together under the acronym SME (for Subject Matter Expert) as if analysts, managers and engineers are interchangeable, but that’s not true. Each of these people has a different function in the organisation, a different relationship with customers and clients, and a different view of the product and how it works.
Technical writers need to know which questions to address to which people. If you ask the wrong person, you not only damage your chances of getting a useful answer, but you may damage your credibility as a responsible member of the team.
Questions for analysts
The business analyst is the person who is responsible for originating or developing the requirements for any product. In some companies the job title varies, and this person may be the product manager, or in the case of agile software development, the product owner or backlog owner.
This person should always know what the clients, real or imagined, actually want, and so they should be able to answer questions like:
- What does this feature do, in simple terms?
- What are users trying to achieve when they use this feature?
- What are the circumstances or the environment in which this feature will be used?
You may find the answers to these questions in a requirements specification document, or, for agile software development, in a user story.
In my experience, these documents may not always give the level of detail that a technical writer needs, or may not completely reflect the point-of-view of the product user. If that’s the case, you just need to keep asking the questions above until you get the information you need. The analyst is the best-placed person to help you, and is also likely to be the most sympathetic to your need to explain complex technology in the most straightforward way.
Using the answers you get
Understanding the different roles undertaken by different people in your development organisation should enable you to direct the right questions to the right people.
If you have made an effort to understand the subject domain, you should be on the way to establishing yourself as a valuable team member. That, of course, is only part of a technical writer’s role. Once you have gathered all your answers from your various sources, you can’t just type them up and declare that you’ve created a user manual.
The technical writer adds value to a development organisation by taking the raw information gathered from the different SMEs and transforming it into effective user assistance materials that support product end users in doing their jobs.
A good user manual, therefore, answers the user’s questions from the user’s point of view, but needs to be based on a deep understanding of the product, which is gained from background research and from asking the right people the right questions.
David Farbey, 2010. Check out the other posts in David’s ‘What to ask…’ series:
Want to know more about working in tech comms? Read our recent tech comms postings, or visit Candidate Services to find work in this field through Firehead, the leading recruitment specialist in Technical Communication, Web Content and IT Recruitment in Europe.
