How to Create Clear, Compliant Technical Manuals

Technical documentation values the product

How can we succeed in the technical writing of documents that accompany and value industrial products and services?

Instructions for use are the essential document to accompany the marketing of a product or software.

Technical writing adapts to international exchanges

How do I succeed in a manual?

I recently read part of the Resolution of the Council of Europe, (old 20 years old) and I... 17 December 1998) on the use of technical consumer goods.

Exciting reading! Mine gold for a technical writer who wouldn't know what to put in his manual, or his user manuals as we have forgotten to call these publications in the vocabulary Technical current correct. No indication of the author of this text, but who it was, it is obvious that the author or authors were experts, well aware of the principles of minimalism. In the end, if members of Twente University had participated, this would not be surprising.

While in 1998 implementing all these recommendations might seem tedious, current component content management systems make these principles much more accessible.

Here are some upbuilding excerpts.

Instructions for use: still useful?

Preparation of user manuals

(a) Consideration shall be given to guidelines, standards, legislation, etc. on employment instructions;

(b) in order to ensure that the information supplied with the products is usable in practice, operating tests shall be carried out . As a result, in a trial of this type of device, a list of the tasks to be performed and the draft user manuals are provided to an appropriate group of consumers. They are then observed while performing the tasks. In the end, observations are recorded on standard sheets;

(c) The contents of the user manuals are structured on the basis of the routine operations which are performed daily by the user: the contents of a manual are based on the tasks which must therefore be performed by the users of the product (principle of job orientation) ;

(d) the user manual provides only information which is not clearly derived from the product itself (a sufficiently clear mechanism which does not require any particular explanation) or from the knowledge and experience of the user, or from the characteristics of the task to be performed (So,principle of providing the necessary missing information).

This does not deny the principles of minimalism set out by John Carroll!

(Unfortunately) who is taking the time today to practice the recommended tests before developing his user manuals?

Due to the limited product lifespan and increasingly ergonomic interfaces, the use patterns are becoming less useful. Yet it is often profitable to invest in real tests!

They sometimes influence the design of the products themselves, but they certainly have an impact on the costs of technical support to users. As for the principle of job orientation, it did not take a wrinkle.

Instructions for use: Minimalism

Typical headings for such instructions are:

• list of product versions covered by the manual, including their different characteristics;

• Table of Contents (in the case of long instructions);

• brief description of the tasks that can be performed by the product;

• information relevant to the action undertaken concerning each task, including safety instructions and precautions, such as advice on installation and commissioning (Task 1, Task 2 . . . ), any general information concerning handling precautions not yet included in the description of tasks, maintenance and the sections concerning the detection and repair of breakdowns;

• Technical data;

• Customer service addresses and hotlines;

• index (for products that perform multiple tasks or for long instructions);

• detachable instructions referring to essential data (for products that perform several tasks or tasks consisting of several separate operations);

• list of typical usage errors, their causes and possible solutions;

• information on ease of use of the product and arrangements for possible recycling;

• information on the accessibility of instructions on media other than printed paper, such as videotapes, CD-ROMs, a website, etc.

Here again, we find key points in the principles of minimalism. Either, tasks, taking into account faults and errors, tables of contents and index...

It is interesting to see the emphasis also placed on the accessibility of this manual on other media.

Structured authoring as a remedy

Separate operating instructions for different models of the same product

Instructions for use may include information on different models or versions of the same product. It is desirable to have separate operating instructions for each model. Especially where confusion could constitute a danger to safety.However, it can be admitted that a single manual concerns several products where differences in product versions do not lead to differences in activities (e.g. where the version of a fax has additional features on some models but the basic operations for sending a fax remain the same).

And bim! Another argument in favour of structured authoring systems:modularity and filtering are the two breasts of the technical writing.

Conclusion

Facilitating the work of technical writers, sustaining the customer relationship

For over 12 years,NeoDoc develops through its software platform Calenco dedicated to the structured technical writing of tailor-made solutions to facilitate, optimize and secure the work of technical writers. The solutions are based on the fundamentals of technical writing as recalled here, and structured authoring. They put user at the heart of the writing. Because facilitating access to the right information for users is also about valuing the product, and sustaining the customer relationship.