What should technical writers ask engineers when writing support materials for a product’s end users? Guest blogger and leading tech comms expert David Farbey wraps up his ‘What to ask…’ series with questions for engineers – previous posts include questions for analysts and managers.
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 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. This final post ends an advice series on what technical writers need to ask the various subject matter experts involved in the product or service they are writing about. Check out David’s previous posts:
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.
2 comments