When considering the writing of product manuals, one question that often comes up is, why don’t the people who designed and built the equipment write the manuals themselves? At first glance, it seems like a sensible suggestion – they will know the product and its many features inside and out, and may also understand how they can be used to meet a specific need or serve a particular application. Surely there’s no-one better to write the user’s guide?
Too much or too little?
In fact, there are a number of potential issues with this solution. In most cases, the product specialist is a fundamentally different person from the end user of the equipment. They (the specialist) understand every nuance of the product and have lived with it on a daily basis for many months or even years. They are likely to have forgotten a time when they didn’t have a deep understanding of the underlying technology, and so the tendency will be for them to assume too much knowledge on the part of the user. They will also lapse naturally into the jargon of the subject, as this is part of their everyday language.
Users, on the other hand, are often not specialists in the field at all, and frequently don’t need to be; they use the equipment as a tool to help them perform one part of their job function. They will thoroughly understand the application of the product, but won’t necessarily need to know every aspect of how it meets their requirements.
Whilst one instinct of the experts is to assume too much knowledge, another is (paradoxically) to impart too much information about the product. Those who are responsible for creating a new product will be understandably proud of it, and are quite likely to describe every nuance of every feature, mode and option, rather than focussing on those that the user will find the most valuable. The expert’s familiarity with the product makes it hard for them to imagine how a new user would approach performing tasks, and so while the expert might routinely use a shortcut, a new user might find this counter-intuitive and would be better advised to follow a more methodical approach until they are familiar with the product.
Play to your strengths
Finally, there is perhaps the most fundamental problem: most developers work in their discipline precisely because they enjoy developing new products. Writing about a product they have spent ages developing isn’t necessarily their favourite task! It can take longer than expected to complete a manual, mainly because the product also needs to be fully completed, which often doesn’t actually happen until it enters production (if then!). By this time, the specialist will be deep into the next development cycle, or working on a completely new product, and won’t welcome the distraction of trying to complete the writing of the guide for a product they regard as finished.
Engineers are adept in grasping technical concepts and are strong in science, mathematics and logic. They can prepare highly technical specifications that describe the product in detail to other specialists. However, these skills do not necessarily prepare them for the task of writing for non-specialists. This is where a technical author can offer real value to a business.
Technical authors bring the approach of engineering to the task of writing, by building up documents in stages to create a finished product that is fit for purpose and specifically designed for its readership. They learn about the product; they ask questions of the experts (an essential source of information); they break the information down into logical steps (for procedures) or succinct chunks (for general descriptions). And they do this with the big advantage that they are not experts in the product, which allows them to place themselves in the shoes of the user much more easily and tailor the content and presentation to suit them.
So while it might seem that a product specialist would be best placed to write a manual, in practice this is often not likely to produce the best manual for the user. Better to ask a writing specialist – a technical author!
© 2019 Tyndale Technical Authoring Ltd
Tyndale Technical Authoring 