Firehead

Our expert guest blogger series continues with tech comms expert, lecturer and consultant David Farbey, who lists the kind of questions a technical writer should ask analysts, managers and engineers in order to create clear, useful support materials for users.

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.

Questions for managers

Development managers need to know where their team’s efforts belong in the overall product development plan, and need to be aware of timetables and dependencies between different features and modules. They should be able to tell you the big picture, but may well be less aware of the detailed requirements than the analyst, and usually they leave the details of product behaviour to their team members.

The questions you need to ask the manager are:

• What is the formal name for this feature, and which project does it belong to?
• What is the expected timetable for development, testing, and deployment?
• Are there any dependencies between this feature and other existing or new features?

In agile software development, teams are supposed to be self-directing and so you won’t hear the term development manager but you may hear about the “scrum master” who is the person responsible for keeping teams on track, and so they would probably be able to answer management questions.

Questions for engineers

An engineer’s view is necessarily product-centric, whether the product is an industrial tool, an item of consumer electronics, or a piece of software. In most companies product development is well documented because there is a business need to keep records for future developments or to meet audit or regulatory requirements.

The language of these detailed descriptions can be quite arcane for someone who is not a professional in the specific discipline, but it is the duty of the competent technical writer to work hard at understanding at least the basic concepts of the product domain. That may well involve doing some serious homework before you meet your developers, starting with internet research and going on, if necessary, to reading entry-level academic text books.

I have always found that engineers appreciate it when you have made this kind of effort, and in doing so I have picked up odd pieces of knowledge in fields as diverse as high-speed image processing, local authority administration, digital photography, and geo-mechanical engineering.

Although some product descriptions do usually exist, it may help you to ask your engineers a few direct questions:

• How has this feature been implemented?
• How does the user interact with this feature?
• What information does the user need before they can use this feature?
• What information does the user have after they have used this feature?

For software products you may wish to ask more focused questions such as:

• Does this feature involve any changes to the product UI?
• Does this feature involve any changes to the product API?

In agile software development environments you are far less likely to encounter a detailed design document, and so you may have to rely on reading the comments in the code itself. Making the effort to do that before you ask your questions is another way of demonstrating to the engineers that you are not trying to waste their time.

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

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 communications, web content and IT, engineering roles in Europe.