We offer various kinds of advice and support in the development of your documentation, such as user manuals, help files, procedures, and work and video instructions. Would you like to have a manual written, and are you looking for a partner? We support our customers by writing, illustrating, translating, checking and managing their manuals.
There are a number of elements that almost always come up in the production of a manual. Knowing what these are and how to approach them contributes to the quality of the manual.
It is important that information on your product be communicated to the user accurately and effectively. Each group of users has its own characteristics, and it’s important to take account of these when writing a manual. A seasoned end user of an emergency-call system has different requirements from someone who’s installing modular pontoon systems. Creating persona's is a good way to get to know your target audience.
Before beginning with the actual writing of the manual, various experts, who are involved in different ways, are consulted. They might be electrical technicians, mechanical engineers, or industrial designers, but also communications advisers or maintenance technicians. These experts provide the product information, each using their own jargon. For the writer of the user manual, the trick is to convey this information to the user in an easy-to-understand way, without compromising its factual accuracy.
Lay ten good manuals next to each other and you can see the correspondences between the tables of contents in each. A good manual allows the user to use a product well and safely, and in accordance with its intended purpose. That is well-nigh impossible if the information is incomplete. In the Netherlands, there is a standard for manuals, namely IEC 82079-1:2012, Preparation of instructions for use which describes, among other things, the contents of a manual. The content described should appear, according to the manual, in every manual. The norm speaks about content that includes such elements as a chapter that gives warnings, technical specifications, installations, commissioning, and maintenance. But it also makes recommendations, such as on font sizes, and offers guidelines for the title page.
Once it’s been decided what will go into the table of contents, it can be populated with information from the aforementioned experts. In the process of actually writing any manual, as much other information as possible should be gathered, such as computer-aided design (CAD) files, marketing materials, and risk analyses. The writer of the manual listens, analyses, selects, obtains, and gets and understanding of the information, asking questions along the way. The key thing about writing a manual is that the writer must have access to, and must actually grasp, all the product information.
In writing a manual it is important to keep abreast of all obligations concerning product safety and liability. In fact, these obligations often entail requirements for product documentation and thus have an influence on the content of the manual. For consumer products, the guidelines on general product safety, 2001/95/EG, apply. These guidelines protect consumers against defective products. And a defective manual is also considered a defect in the product. When it comes to professional products, CE directives often impose requirements on the manual.
As soon as the information is complete and well organised, it can be converted into texts that are easy to understand. Product information is generally edited (into instructional texts) for the manual. Marketing materials are often not instructive, and technical information is often too hard to understand for the target audience. The target audience still plays a central role, because the information must be communicated to the user. There are two principles that play a significant role in conveying information to users: minimalism and Simplified Technical English (STE). The latter cuts the amount of text, so that often-superfluous details are eliminated from sentences. This yields a reduction of about 30%. STE is set out in the ASD-STE100 standard. Doing an Simplified Technical English training is highly recommended, as the standard is a complex docuement. The principles of minimalism ensure that the time needed to learn something is cut by 30%, and that the user remembers 25% more information.
Texts can be supported by illustrations, which can also replace texts altogether. Because illustrations replace words, they can reduce translation costs. In addition, pictures paint more than a thousand words. Striking the right balance among text, illustrations, and white space improves readability and ease of understanding.
Manuals are best known in hard copy, mostly because it is made mandatory by legislation. Online and “on-device” manuals are gaining in popularity. There is a range of packages for the publication of these various output forms. These authoring, editing, and publishing packages make use of a database in which texts are organised. Managing these texts well in a modular fashion (and with accompanying translations) encourages re-use and thus reduces translation costs considerably.
Madcap, Framemaker and Author-it are widely used packages in the world of technical documentation and the writing of manuals.
For a detailled case study, read this blog post.