Electronic Information Commerce		Table of contents		Indexes		Common Business Library (CBL)

Graphics-based Product Documentation: Principles and an Application

Camillo Acerbi

R&D Director

IDM Esperti in Comunicazione Tecnica 8, via Virgilio
Forlė Italy 47100
Phone: +39 0543 756699
Fax: +39 0543 756600
Email: idm@mbox.queen.it Web: www.idm.it

Biographical notice:

Dott. Camillo Acerbi was born in 1969 and lives in Cesena (Italy). He attended Bologna University, getting a degree in Physics. In 1994, he won a research fellowship at the National Institute of Nuclear Physics. There, he developed numerical simulations for astroparticle experiments. The resulting papers were published in international reviews. Since 1997, he has been working at IDM (IDM Esperti in Comunicazione Tecnica) Company as an analyst/programmer, in charge of the R&D department. Currently, he is primarily developing the Activ.Suite, a project for the electronic publishing of product documentation.

ABSTRACT:

Product documentation assumed a fundamental role, as a tool for safety and prevention, and as important added value to products. Manufacturers experience that good information is a crucial feature, both for their own legal safeguard, and for customer satisfaction. Thus, more and more companies get involved in the quest for product documentation that meets the regulations and is appreciated by the users, with lower costs at the same time.

This challenge seems nevertheless discouraging, owing to the inadequacy of procedures and tools. In the paper, we tackle these problems, and present the solutions adopted by IDM . This is a leading Italian company in product documentation, which for more than thirty years has been supplying enterprises with Instructions for Use and Spare Parts Catalogues.

We first discuss the principle of visual communication, "You see - You think - You use", which states that illustrations transmit information better than text does. A number of arguments to support it are given, with some hints on how to choose between representative and symbolic graphics. Other principles of technical communication are also presented. Modularity avoids redundancy and permits maximum information reuse; links from legacy and production data permit easier and quicker updates. The role of standard formats, such as CGM for graphics and XML for text, is emphasised.

Concerning the tools, we point out that a stricter bottleneck is present in the distribution phase of documentation, where we deal with hardcopies: these are costly to produce and difficult to consult. On this subject, an application story is presented in the paper. IDM developed a software control, named Activ.ED, which interfaces withInterCAP's ActiveCGM Browser to manage electronic Spare Parts Catalogues. This control adds dedicated functions (such as parts searching and ordering) to usual hotspot features, and permits the highest application of those principles we described. In fact, we deal no longer with hardcopies, but with a graphics-based communication, which extracts information from project data and publishes it on the Web, for on-line consults and revisions on the fly.

During 1998, hundreds of new directives regarding product safety have been issued.

"You see - You think - You use", that is to say: illustrations transmit information better than text.

Cave incision of 2,500 years ago in Valcamonica (Italy): no-one can understand the TEXT...

Reduction of text by increased use of illustrations enables large savings to be made.

Representative and symbolic images of an electric bulb: different figures for different uses.

Example of gestural illustration: adjusting pressure.

Example of operational flowchart: troubleshooting guide.

The path from legacy and/or design drawings to ActiveCGM Author.

The welcome page of Activ.ED, with the first step to the catalogue: the language choice.

The user enters a S/N, which points Activ.ED to the correct machinery configuration.

The toolbar of Activ.ED gives access to the catalogue and other services.

The first page of the Spare Parts Catalogue: the general figurative index of machinery.

An assembly figurative index of the catalogue. Note the magnifier and the locator on the right.

An active IPB, with the dialog box for part ordering, also displaying part data.

The order list. The user only has to enter quantity, reducing errors of transcription.

The same IPB of Fig. 14, now in "show references" mode. This is used for printing hardcopies.

Introduction

Manufacturers are subject to obligations and responsibilities right from the product's design phase; it is in this phase - i.e. the furthest possible upline - that they must safeguard the final user in every way, also by providing correct product information. Documentation thus assumes a fundamental role: not merely as a guide to use, but also as a tool for accident prevention and safety in general.

For its part, the market registers an increasing demand for those products that in addition to such factors as reliability and durability, offer an efficient service network, and valid supporting documentation. Manufacturers are now aware that good information is a crucial feature, both to protect their own interests, and to ensure customer satisfaction.

Companies are thus increasingly committing themselves to a profound change in product documentation. The process of European unification has certainly given a boost to this trend. The European Community is continually issuing new standards for the safety of machines, and imposingclear and complete Instructions for Use, that take into account the cultural and behavioural characteristics of all the people that will interact with the product, in the course of its expected life (cf.). Furthermore, the coming of the European global market makes documentation an increasingly important added value to products.

Nevertheless, the common goal is not only to provide documentation that satisfies directives and is appreciated by users; it is also to produce such documentation more rapidly and economically. Many companies engaged in this challenge, however, experience difficulties and discouragement. In some cases, companies still do not have the necessary organisation, either from the operating procedures point of view or the specialist personnel required. In other cases, the problems should also be ascribed to the inadequacy of tools. Information Technology, which revolutionised office automation with tens of excellent programs, does not seem to give such authoritative solutions for the field.

In short, what companies are looking for is a "system", in terms both of principles and tools, that will enable them to obtain clear and complete documentation; not only simple and pleasant to consult, but also inexpensive to produce, distribute and update. Are they perhaps asking too much?

Principles of Technical Communication

It is now a universally accepted fact that product's design phase is at least as important as actual manufacturing. It is not surprising, therefore, that significant resources are dedicated to this phase, both in terms of time and money; similarly, no-one denies that to become a designer requires study and considerable experience.

Similar accepted facts are much rarely voiced when talking of technical documentation. This situation is the result of a number of factors, which still persist, in endemic form, even in modern, cutting-edge businesses. An ill-judged sense of saving, for example, induces many companies to entrust the preparation of Instructions for Use to people without any specific training. Assigning such tasks to experts in the sector, however, would enable these hidden costs to be significantly lowered - i.e. the processes of obtaining information, preparing it for publication, and distributing it - which, taken together, have considerable influence on the final cost of the product.

It should not come as a surprise to anyone that in this field NO planning is involved. But are we really sure that the design phase is of so little importance in the technical information workflow? And if there exist principles and procedures which, when known and applied, could contribute to the development of that more effective, less costly documentation, that all companies aim for?

"You see - You think - You use"

The theory of communication, like thermodynamics, has its "zero principle", which supports and governs all the others. Its premise goes more or less like this: "Illustrations transmit information better than text". Some call it the principle of visual communication: we prefer to call it the principle of "You see - You think - You use" - in contrast to what happens with textual communication ("You read - You hope to understand - You try to use"!).

As with all principles, this one cannot be demonstrated in the absolute sense; there are, however, many good arguments to support it:

Illustrations do not require any specific education to be understood . An error which technical writers can easily commit is that of presuming their own cultural and terminological frame-of-reference is shared by all their readers. There is no need to involve the newly-developing countries, in which illiteracy is still widespread, to understand that this is not always true: probably we have all had the experience at some time of puzzling over engineering manuals. The recourse to figures, to support or partially replace text, enables us to reduce these risks.

Illustrations can be understood faster . Unlike text, which must be read and understood, illustrations are immediate and transfer information with just one glance. This is particularly important when messages of warning or danger must be communicated.

Illustrations "do not age" . The message transmitted by a figure is much more resistant to the passage of time than text, which is exposed to the evolution of phraseology and changing terminology. Just think of the cave drawings of thousands of years ago, still today perfectly comprehensible (see Fig.ACE-003).

Illustrations are easier to remember . "Cognitive research has shown that memory for pictures tends to be better than memory for text." (K. Schriver). This is particularly true when the figures are used for describing a work sequence that the operator will have to subsequently put into practice.

Illustrations do not require translation . This means that the possibility of errors due to incomprehension and poor translation is drastically reduced. But it means above all lower costs: a recent study carried out by IDM has shown that, using illustrations to the maximum while reducing text, brings savings of up to 30% for a "typical" manual translated in all the languages of the European Union. The increase in cost due to the greater need for figures, in fact, is amply compensated by the economies deriving from the reduction of the amount of text that has to be translated (see Fig.ACE-004).

Graphics types

In daily life, however, one can see that not all illustrations achieve what has been described above. There are confusing figures, complicated ones, those that are incomprehensible or even misleading. For this reason, our earlier principle needs a stronger formulation, namely: "GOOD illustrations transmit information better than text".

At this point, the problem becomes that of defining what represents a "good" illustration. The answer is that, irrespective of a number of general and somewhat obvious characteristics such as clarity and simplicity, there is no valid recipe for all situations. There are, in fact, different types of figures, each with its own particular features, and each suitable for different types of information to be transferred. Generally, we can distinguish two families of graphics, which basically reflect the realism/abstraction antithesis that is typical of visual arts:

Representative graphics . This family includes exploded drawings, colour cutaways, and all those illustrations that are used in reproducing reality in a substantially faithful way. These figures are widely used in Spare Parts Catalogues and in manuals, particularly in the mechanical sector. The risk to be avoided is that of excess details which, with the intention of rendering the picture more recognisable, results in distracting or confusing the reader. In addition, a highly detailed illustration can only be re-used with difficulty, as it is too specific to a single situation.

Symbolic graphics . The best way of describing something is not always that of showing it as it appears. No-one, for example, would dream of using realistic images of diodes and resistors in wiring diagrams. In these situations, it is advisable to make use of symbols. In some cases, the symbol is obtained from the representative view by means of iconic abstraction, a process of distillation in which all non-essential details are eliminated, stylising the forms to the maximum. Architectural symbolism is a first-rate example. Other times, the symbol is "suggested" by the function carried out by the object or with the object - above all when having to represent a concept or an action. This is the case of electrical symbolism. In using these types of illustrations, it is necessary to take into account the fact that, however simple and instinctive they are, symbols require a minimum degree of interpretation, based on conventions not necessarily known to all users.

Rather than enter into the details (something for which the reader should refer to Gebhardt & Porter) we prefer to present two examples taken from our work methodology, namely, two types of graphics, belonging respectively to the representative and the symbolic family:

Gestural illustrations . These are figures which contain parts of the human body in association with tools, together with symbols that enable the user to understand clearly and immediately the interaction between the operator and the object concerned (see Fig.ACE-006, for example).

Operational flowcharts . The symbols used in flowcharts may be profitably applied also in the field of technical documentation. An example is shown in Fig.ACE-007, in which a traditional "trouble-shooting" text has been converted into decisional and operational form, in such a way as to rapidly guide the operator towards correct diagnostics and the required solution to the problem.

Other principles

Having examined the form towards which technical communication should tend in order to achieve maximum economy and effectiveness, it is now necessary to make a few brief operative observations. We present a number of principles which address structure and input/output issues for product documentation.

Modular structure of information . Modularity is indispensable in avoiding redundancy: the presence of duplicated items of information gives rise not only to a waste of storing resources, but to the need to intervene on each individual copy in the event of modifications or updating. In addition, a modular structure enables the maximum re-use of the material. Consider, for example, a single functional group fitted on different machines: the relative tables of the Spare Parts Catalogue and the relative pages of the Service Manual can be produced just once and then re-used in the documents prepared for all subsequent products. To do this, however, it is necessary to handle the documentation planning accordingly, sub-dividing subjects and drawings in autonomous units, which can then be re-arranged as required to suit different situations.

Recovering native data . Until a few years ago, the Drawing Office and the Documentation Department led rigorously separate lives. The designers prepared assembly drawings and compiled the parts lists: next door, the documentation specialists prepared ex-novo exploded drawings and compiled ex-novo spares lists, for the same machine. Today, it is possible to obtain isometric views directly from assembly drawings on 3D CAD, and the extraction of data has been simplified as well. The direct withdrawal of native information enables costs to be brought down, means faster production of documentation, and contributes to the reduction of errors.

Use of standard formats . One of the major sources of problems and waste in the handling of technical documentation is the co-existence of information in many different formats, at times mutually incompatible. You can see an example of this situation simply by counting all the extensions of the files present in your company's Information System; a count which typically runs into dozens. Very often, a same kind of information has been coded in many different ways. In the field of illustrations, for example, there may co-exist raster scans of paper-based data, 2D and 3D CAD vector files, documents of programs for graphics or electrical schematics, and so on. This situation makes the exchange and re-use of information very complex or even impossible. It is thus a good rule to eliminate, where possible, different programs that carry out the same task and, in any case, to try to gather together - by means of export routines or filters - all the documents into a single common format. This common format should be a recognised standard, such as XML for text and CGM for graphics, so as to guarantee compatibility also with the rest of the world, and to safeguard oneself against the "volatility" of proprietary formats.

From principles to applications: a case study

Good principles are a necessary but not sufficient condition to obtain good product documentation. One also needs appropriate tools to make up and manage information in accord with those principles. Unfortunately, the situation looks bleak under this point of view too.

Among others, a stricter bottleneck is present in the final phase of the documentation workflow. There are powerful CADs to create the drawings, and advanced word processors to write the texts. There are highly evolved publishing suites to combine those drawings and texts. Now, what finally comes out to the distribution? Usually, a bunch of hardcopies, which are costly to print, impossible to update, and - often - difficult to use.

Several companies, attracted by fashionable words such as "multimedia" and "electronic format", which sounded like panacea, fall then into the "scanner trap". Being inconvenient to distribute information in native format, some businesses get convinced that a scanned copy of documents, to be distributed on a CD-ROM, could be a proper answer. However, they did not realise this was just another step added to the old cycle, without any real benefit for the end user.

The development

IDM Esperti in Comunicazione Tecnica (IDM for short) is a pioneer Italian company in advanced product documentation. For more than 30 years, it has been supplying businesses with all those services that relate to technical information: user instructions and other manuals, IPBs (Illustrated Parts Breakdowns) and spare parts catalogues, risk analyses and CE conformity declaration consults. In 1998, IDM employed 30 people, mostly technical writers and CAD operators, with revenue reaching 2 millions US$.

In its activity, IDM experienced this same inadequacy of tools. Therefore, in 1987, Mr. Mambelli, IDM owner, decided to develop an application for the electronic publishing of exploded views, with hotspots for navigation and spare parts ordering. The project, named D&SPOS (Drawings & Spare Parts Ordering System), failed mainly because of coding troubles. Nevertheless, this unsuccessful attempt was an important experience and a harbinger of future solutions. Ten years later, in fact, IDM learned about "an InterCAP software that activates drawings "; this was, of course, the ActiveCGM technology.

IDM got in contact with InterCAP Europe and immediately started working to obtain the features previously planned for D&SPOS. Moreover, in the meantime, the importance of communication principles had become more and more evident; therefore, IDM decided to plan and develop the application in strict accord with the framework presented in the previous Section:

"You see - You think - You use" . Spare Parts Catalogue is graphical by nature; nevertheless, some text is present in indexes and in instructions for order. IDM decided to use figurative indexes, so that users can reach the desired IPB through hotspots in illustrations of the overall machine. Instructions files were also made up with many more images than usual. Concerning the application itself, it was decided to build a totally graphical interface (buttons, toolbars,...).

Modularity . A first-order, obvious modularity is that of having just one copy of identical IPBs which are present in different machines. IDM wanted more. Sometimes, one has IPBs with same illustrations but different parts lists: think, for instance, to an electric generator which is 220V/50Hz for the European market and 110V/60Hz for the American one. In such cases, one can keep just one IPB only by splitting graphics and data. Therefore, the first idea to include part specifications inside the CGMs, by means of group extensions, was discarded, and it was decided to keep data in external files.

Legacy reuse & standard formats . As we said, the application was to be based on the ActiveCGM technology. A general workflow was laid down, fixing the procedure to obtain a CGM file from several native sources. These range from handmade exploded views on paper yellow with age to 3D CAD files. In Fig.ACE-008, you can see a sample of this flowchart. The three main paths are:

Old exploded views on paper are first scanned, then imported into ActiveCGM Author, and mapped with vector contours. Raster and vector layers are saved as a single hybrid CGM.
More recent CAD exploded views are converted from native format to CGM. This may require one or more passages depending on the source program.
Current 3D design data are used to directly generate CGM isometric projection.

Concerning parts data (specifications, designations, prices...), it was decided to directly extract from the company's database itself.

In addition to these requirements, IDM also wanted to radically settle the question of medium. The Internet was chosen as a second distribution channel, in addition to CD-ROM. In such a way, users can download on demand latest versions and real-time upgrading of data and drawings. Therefore, after a first prototype using a dedicated reader (ActiveCGM Runtime), in October 1997 the development moved to the Browser, an ActiveX control which allows CGM viewing into Internet Explorer.

All these features were accomplished in another ActiveX control, which interfaces with ActiveCGM Browser via VBScript. At the first access, Explorer automatically installs this control, together with the InterCAP viewer. An extensive treatment on technical matter is beyond the scope of this article; for some more details see our previous paper.

After several months of work, the application had grown so much that it needed proper life. It was named "Activ.ED", which stands for Active Exploded Drawings and reminds of ActiveCGM. At the same time, IDM decided to start developing Activ.UM, the User Manual companion of Activ.ED. The initial requirement is to access instructions through the same drawings used by the spare catalogue. Basically, when clicking a part, the user can access information on its replacement and adjustment. This is why IDM talks of Activ.Suite.

The implementation

The first actual implementation of theActiv.Suite was carried out in 1997 for the Spare Parts Catalogue ofBiesse Group . This is a world-leading group in woodworking machinery. In 1997, its billing reached 220 millions US$, with thousands of installations in five continents.

Biesse experienced great difficulties in the timely sharing of product information, especially exploded views. This had strong repercussions in the after-sales service, for exploded views are heavily used in the spare parts managing and repairing instructions. These difficulties were due to the sizeable variety of Biesse production. There are more than 50 machine models, each rapidly evolving in improved releases. There are several optional extras, which can be mounted or not. In addition, customers often ask for customisations or adjustments for special uses. To sum up, it is not so far from the truth to affirm that almost every machine differs from all others!

In such a situation, the principles presented in Section 2, and modularity in particular, were much help. For Biesse, IDM drew or re-drew on a modular basis about 4500 exploded views. Each basic group or assembly, in each standard or customised release, received a distinct numbered IPB. When a machine left the factory, its final, actual configuration determined the list of IPBs to compose the spare parts catalogue. The documentation man had only to pick the right numbers.

Nevertheless, the "hardcopy bottleneck" was still there. Costs were high, corrections on-the-fly were difficult, and parts search was lengthy and was a source of errors. Therefore, Biesse willingly accepted to act as a Guinea pig for the first implementation of Activ.ED.

The desire of Biesse was that the catalogue was not to be directly part of the business's web site, due to security problems. Therefore, we planned a two step path: at first, the drawings are distributed to customers and dealers on CD-ROM (while being net-available only inside the Company's LAN). In this phase, each user receives the same CD, including all existing activated drawings, and a floppy disk with the configuration of his own machine. In such a way, he can only navigate in a selected subset of drawings and get parts specifications that exactly match his situation. As soon as the access control issues are settled, the system will migrate to the Internet, where users will deal directly with Biesse database. To arrange this transfer to the Internet, the CDs include a mirror copy of the site, and the catalogue is accessed via an ordinary web page.

Currently, about 350 drawings have been activated, covering six leading models (Rover line). First disks are on press, while the catalogue is already installed and used on the LAN. Mr. Morelli, in charge of Biesse's Service, recently wrote: "This application is great. It is the future of product documentation. It's very user-friendly and customers will appreciate it. I think we should get ahead with the project and implement the user manual too." And Mr. Lancioni, EDP manager, is a keen upholder of CGM solutions and is constantly involved in testing Activ.ED.

A brief tour in Activ.ED

As we said, Activ.ED is hosted in an HTML page; this contains the VBScript and displays just one CGM area. The first drawing that is loaded in this area is not yet an exploded view, but it is the graphic interface of the catalogue, i.e. background, logos, and toolbars.

In order to guide unskilled users, a sort of fixed course was set. Once the user enters the catalogue, he can choose the language for dialog (Fig.ACE-009). This is not only a service to the customer, but it is a real manufacturer's duty. A recent European regulationstates that product information should be present in the language of each destination country. The Activ.ED implementation for Biesse currently provides six idioms, but it can be easily extended.

Then, the user has to enter the serial number for the machine of his interest (see Fig.ACE-010). This is a particularly crucial point, as the S/N is the key to identify the machine configuration. This will be used in all following queries to retrieve correct part data and/or drawings.

Finally, the user must choose what operation to perform with Activ.ED. Through the upper toolbar (Fig.ACE-011), he can now access the spare parts catalogue, he can carry on a search for a part or an IPB, or he can edit and manage an order list. A button is also present to access the user manual, as the interface is already arranged for integration with Activ.UM.

Let us enter the catalogue. The overall view of machinery is loaded in the CGM area (Fig.ACE-012). Navigation to functional assemblies is performed through enhanced hotspots. These are not simple links to other drawings, but conditional links, depending on the given S/N. In Fig.ACE-013, the user reached an assembly exploded view, which acts as a second-level index, due to machinery complexity.

Again through enhanced hotspot navigation, the user can finally reach a real IPB (Fig.ACE-014). Here, he can retrieve part data (such as the number, price, and specifications) and place the order, with just a mouse click. Orders are added to a list (Fig.ACE-015), which can be easily corrected and printed, while a subroutine checks against duplicate requests.

In order to obtain hardcopies matching the former catalogues on paper, a special button was added in the lower toolbar. This one hides the Activ.ED interface and other unwanted graphics (such as the "locator", which shows the current position in the machine), and makes visible callouts and parts list (see Fig.ACE-016). It is important to notice that the parts list is not included in the CGM file, but it is generated on the fly, again depending on the given S/N. The list is added to the drawing in real-time, as a redline.

A product demo of Activ.ED can be found at IDM web site.

Conclusions

In its many years of work, on which this paper is based, IDM had a chance to experience the benefits deriving from the adoption of valid principles for technical communication. A strong use of graphics - which reduces translations and transmits messages "at a glance" -, a methodical use of modularity - which avoids redundancy and permits maximum information reuse -, a complete use of links from production data - permitting easier and quicker updates - may result in sizeable saving and higher readability of product documentation.

Concerning tools, the stricter bottleneck, which is present in the distribution phase, can be overcome thanks to standard-based, Internet-enabled applications, which are to be developed in accord with the above principles. IDM is currently engaged in three fronts:

First, they are working to complete the migration to the Internet. This requires no data modifications and only little adjustments to the info retrieving procedure of Activ.ED.
Secondly, they are continuing the development of Activ.UM. Again, Biesse acts as a Guinea pig for this.

Finally, they want to "industrialise" the Activ.Suite. The control was partially tailored to Biesse's needs; now it needs a more general form. Other companies are asking for a similar tool, and it is preferable to manage a single parametrisable program rather than several customised ones.

Therefore, the work with the ActiveCGM is still in progress, and we cannot express definitive conclusions. Nevertheless, with Activ.ED we are already experiencing this technology can be the right tool not only for a few big companies, with great budgets and organisations, but also for the thousands and thousands of medium-business enterprises. Therefore, a major challenge for IDM - and for all companies like IDM - must be the untiring and intelligent propagation of standard-based solutions, thanks also to integrated applications and special add-ons like Activ.ED.

Acknowledgments

The author wants to thank all the staff of InterCAP Graphics System, for their effective and timely technical support.

Bibliography

: Directive 89/392/EEC - Annex I - Section 1.7.5 (1989)
: Schriver, K., Dynamics in document design, Wiley & Sons (1996)
: Gebhardt, J. and A. Porter, The global language, paper presented at CALS Europe (Frankfurt, August 15, 1997)
: Acerbi, C., A new tool for the electronic publishing of product documentation, paper presented at IGUA '98 Conference (Annapolis, October 7, 1998)
: http://www.idm.it/red_uk.htm (needs Internet Explorer and 32-bit Windows OS)


Electronic Information Commerce		Table of contents		Indexes		Common Business Library (CBL)