Writing a manual: The main task in technical editing

One of the daily tasks for technical editors is assembling various kinds of information on a product – they write manuals. There are different types of manuals: operating instructions, user manuals, installation manuals, online help and many more. Altogether, along with the compliance with normative and legal demands by the producers, the intelligibility and comprehensibility of manuals and the online help are an ideal instrument for customer retention. Often, the manual is the first thing the customer looks at, either when searching for a suitable product. The quality of the manual is closely related to the judgment on the product.

DIN EN 82079: Writing manuals made easy

The norm DIN EN 82079 specifies fundamentals for the creation of manuals and is a helpful support for the writing process. The Machinery Directive 2006/42/EG focuses on manuals for machines. We have compiled the most important information for you. The norm provides an instruction including the integral issues for writing manuals, as well as an appendix with a description of the planning and creation processes. It is both a guideline for the content and a procedure model for the creation. The following sections are particularly interesting for writing manuals or an online help.

Who creates your manuals? You have questions?
Consulting

The key points in the norm concerning manuals in short:

  • Principles
    The level and the information depth of the manual shall be in line with the target group, with the main focus on the language: Manuals become target-group-specific with intelligibly written texts and consistent terminology. A main purpose of a manual is the warning of dangers arising from the product. This shall be ensured by safety notes. The documentation has to be provided in the right media: an installation guide for a software, for example, should be available as a printed manual and should not only be available as online help accessible after installation.
  • Content of user manuals
    The norm contains 15 sections on what should be included in a manual. This includes such diverse issues as the identification, for example with a print number and date of issue of the document, to the model or serial number of the product to the intended use of the product. There should be information on the permission to change the product and safety-related notes in the manuals. How do users have to transport the product, put it into operation, maintain it and depose of it? Which information on accessories, especially tools, or on repairing the product have to be in the manual? Additionally, the structure of the manual is covered: If you have to write more than a manual for the operating instruction, the different manuals have to be clearly identifiable.
  • Creating user manuals
    The norm addresses text intelligibility with a whole section. Apart from general rules, which are valid for writing manuals, editors shall develop information classes for the manuals which match the text function. The structure of the manual and the style of writing and wording are mutually dependent and shall be documented in an editorial guide.
    Style Guide
  • Appendices A to E: Evaluation of the conformity with this part of the series of standards 82079
    The appendices contain checklists with which you can check the conformity with the norm. Has the manual been created according to the norm or do you have to revise it? The norm also contains a description of the editorial processes for creating manuals.

Writing manuals for machinery and plant engineering: The operating manual.

The technical documentation in machinery and plant engineering describes the entire life cycle of the product. The manuals cover all aspects and follow the Machinery Directive 2006/42/EG, which is valid for both internal and external technical documentation. External documentation refers to all manuals the producer delivers to the customer.

Output formats: printed or online

Operation manuals which are relevant for the safety and the health protection of the users shall always be accessible as a printed manual. This is required, because not every user can read the operating manual published electronically at any time. In recent years, however, it has become more and more common to deliver a printed manual, but provide an additional online edition. That way, producers can easily update their manuals.
Content Delivery Portal

Translation of operating manuals

The manuals are an integral part of the machine. They contain every necessary information and all instructions for the safe use of the product. This is why they are translated into the official language of the respective country.
Translation

Text intelligibility and target group orientation

A vital motivation for a well-written and intelligible manual is ensuring the safety of the users. In that respect you can read in many directives that the text intelligibility and the target group orientation are getting an increasing significance: The operating manual shall accommodate the level of general knowledge and acumen which can be expected from the operators.
Intelligibility

The following issues have to be described in the manual:

  • Characteristics of the producst, performance and functions
  • Intended use
  • Predictable misuse which could not be ruled out constructively

For warning and safety information which shall protect the users from danger, the editors have to be able to access a proper risk evaluation.

Producers have to write and deliver the following types of manuals:

  • Assembling instruction
  • Installation guide
  • Operation guide
  • Maintenance guide

Writing manuals for software applications

The manual for a software application is usually delivered with the software product as an online help. This entails the biggest difference to a manual for machinery: An online help offers much more possibilities than a printed manual. Still, modern content management systems enable editors to publish in different output formats, so that the documentation can be created by single source processes.

Naturally, there are not only differences, but also numerous common features of the online help for software documentation and printed software manuals. There are good reasons why the online help has replaced manuals in software documentation, but it has retained some of the books’ structural elements. The structural order of a hierarchical table of contents with main chapters and subchapters, as well as an index can be found both in manuals and in an online help.
Software documentation