Imposing Intelligence on Graphics: Using HyTime Hyperlinks with Non-SGML Data   Table of contents   Indexes   Plato, SGML and revolution
 
 

Integrating product model and the documentation: A practical approach
 
Pekka   Siltanen
  Senior Research Scientist
  VTT Information Technology
P.O. Box 1203
VTT   Finland  02044
Phone: 358 9 456 5953
Fax: 358 9 456 7052
Email: Pekka.Siltanen@vtt.fi Web: www.vtt.fi/tte/
 
Biographical notice:
 
Pekka Siltanen
 Finland  
Kostiainen, Kaisa
 VTT  
 VTT Information Technology  
 
Mr Pekka Siltanen is a senior research scientist at VTT (The Technical Research Center of Finland). He received his masters degree (M.Sc, 1990) and licenciate degree (Ph.Lic, 1995) in Computer Science from the University of Helsinki. He has been carrying out several research projects in document management systems, product modeling, image processing and CAD development. Currently he is working as a project manager in the EU funded DOCSTEP project for developing product management system in co-operation with Valmet Corporation.
 
Kaisa   Kostiainen
  Research Scientist
  VTT Information Technology
P.O. Box 1203
VTT   Finland  02044
Phone: 358 9 456 6080
Fax: 358 9 456 7052
Email: Kaisa.Kostiainen@vtt.fi Web: www.vtt.fi/tte/
 
Biographical notice:
 
Kaisa Kostiainen
Leikas, Markku
Valmet Winders
 
Ms Kaisa Kostiainen is a research scientist at VTT (The Technical Research Center of Finland). She received her M.Sc. degree in Computer Science from the University of Helsinki in 1997. Her research interests include integrating SGML with product models and with (virtual) electronic learning environments. She has been working in the DOCSTEP project and several other document management projects as an SGML expert.
 
Markku   Leikas
  Valmet Winders

Email: Markku.Leikas@valmet.com
 
Biographical notice:
 
Markku Leikas
 
Mr Markku Leikas, M.Sc (Tech) and Manager, Automation Engineering, has over decade experience in managing automation area software development projects, mainly for Paper production and Energy distribution areas, including also installation and maintenance phases. He has recently concentrated in graphical user interface and standard interface questions, SGML-based documentation and its integration to automation systems.
 
ABSTRACT:
 
A document management system for managing papemachine documentation was implemented. The system is based on the dividing the documentation into the document components that are linked to the product structure using specially designed interface tool.The document components are stored into the SGML database allowing to assemble customer tailored document configurations. Document translations are managed using SGML database sharing mechanism. The system is partially in production use at the Valmet Winders’ unit.
 
 

Introduction
 
A complicated machinery consists of thousands of components which are assembled together to make upthe complete product. Each of these components may have several variants and the machinery delivered to different customers is often unique. Managing these product configurations is often complicated during the whole product life cycle which may be e.g. 30 years.
 
Another dimension to the problem is added when technical documents of these configurations are managed. Technical documentation, such as operating instructions, technical descriptions etc., are delivered as different configurations similarly as the product it documents. However, the problem of configuring documentation may be even more complicated than configuring the corresponding product. This is because the process of managing documents is independent of the product configuration management process. The changes in the product are mostly reflected on the documentation, but in addition the documents have a life cycle of their own: corrections are made, customer-specific changes are created, documents are translated etc.
 
Therefore, the document management system must be capable of not only storing the documents but also of helping to solve more complicated problems, such as:
  • how to deliver each customer documents that document only those product components that were delivered to that customer,
  • how to handle the product and document revisions after the product is delivered,
  • how to manage document translation, trying to minimise re-translation of such document elements that have already been translated?
 
The solution that seems to be natural for managing complicated document configurations is to interpret the documentation as part of the product. This means that each product component in the product management system contains its own documentation and each product configuration therefore automatically contains the right documents. A lot of research has been done on this subject, especially on ways to integrate the standards of product modelling and structured documentation.
 
This paper describes the work that has been done for implementing a document management system, called Valdoc, for Valmet Corporation, together with VTT Information Technology. The system is based on the idea of linking SGML data and the STEP based product structure, but a lot of simplifications have been made because the existing product data management (PDM) systems seem to have quite poor STEP capabilities. The following sections describe the previously suggested solutions that form the basis of our application, the application scope, the basic components of the application and our product and document models.
 
 

Integration of product structure and technical documentation
 
The product documentation is typically created at the end of the product development cycle. The engineer designing the product is the best expert also for giving information for the technical writer creating the documentation, but in many cases, the lack of time and proper tools hinder the efficient and accurate information transfer.
 
Communication efficiency can be increased by defining product models that let the product designer generate the documentation information while designing the product. The technical writer can use this information and transform it into an appropriate format for different purposes. This can be implemented by integrating two standards STEP (ISO 10303) and SGML , . The benefits received from the integration seem obvious: they are both ISO standards that are widely accepted and they share a common background - STEP is used for modelling product information while SGML models document structure.
 
The concept of SGML_STRING was introduced by the Swedish Association for CALS . SGML_STRING offers a way to store information that is structured in SGML format within STEP models. It allows the product designer to store the documentation similarly to all the other product information.
 
There are some practical problems that the approach of including the documentation into the product model does not seem to solve yet. For example, companies seem to adopt the concept of producing documents in SGML much more easily than adopting STEP for exchanging product information. This is partly because adopting STEP seems to require big changes in company processes and partly because not even all the major product data management systems can support STEP. We do not argue that STEP would not be the right way to go, but it seems that there is a large number of big companies that will not use STEP during the next couple of years but still need an intelligent way to control their product documentation.
 
Also, it seems that the problem of customer document configuration can more easily be solved outside the product management system. It is an inviting idea that the product configuration uniquely defines document configuration - meaning that if we know which product components are delivered to the customer we can always automatically get the document components attached to the product components and create customer documentation by assembling these documents (Figure ).

 
Product configuration describes the document configuration

 
 
In practice configuring the documentation it not that straightforward. If two customers receive the same product component, all the documents describing the component are not necessarily the same for both customers, even if the document language and terminology in the documents are the same. The documents describing the mechanical structure of the components are probably the same in both cases, but the component may be operated differently according to some external automation device, which causes e.g. operation instructions or safety documents to be different.
 
STEP standard has mechanisms for handling such problems as the ones described above, but since the idea of including SGML documentation in the product model is still quite new, PDM systems (even those that support STEP) would need to be tailored quite heavily to build document management functionality in them. We have adopted an approach that separates document and product management, and uses product structure information only for creatinga linking between these two. This enables us to rely on existing tools for managing SGML documents, without having to re-invent the wheel on the product management side.
 
 

The Valmet document management application
 
 

Paper machine documentation
 
Valmet Corporation is the leading manufacturer of paper and board machines and related process control in the world. Paper machine is a product that hardly can be compared with any other machine, as it is more like a factory than a machine. A paper machine may be over one hundred meters long, forteen meters high and ten meters wide. At one end of the machine, pulp is fed, it is then dried and pressed and, at the other end paper rolls of a width five to ten meters are produced, at a speed of close to hundred kilometres of paper in an hour. The machinery is highly automated, it is run by just a few operators and its automation system complexity can be compared with only the automation system of a big aeroplane.
 
Each paper machine manufactured is unique. However, it is modularily designed and a great deal of its components are similar in each paper machine. A lot of the components are modified according to customer needs but their basic functions are similar for all the customers in all the product configurations.
 
The manufacture of paper and paper finishing machinery is a global business. Valmet has production plants and service operations in all of its main market areas in Europe, America and Asia-Pacific.
 
The paper machine documentation has traditionally been delivered to customers on paper. As a manufacturer of paper machines, Valmet Corporation is naturally not very motivated to support the attempts to diminish the use of paper, but it has increasincly been delivering documents also in electronic format. The reason for the need of electronic document is obvious: the amount of documentation of the whole paper machine may be calculated in a number of truck loads or cubic meters, not in th eterms of number of pages. For example, Valmet Winders unit delivers over 20000 pages of textual documents yearly, and their Winder forms only the last few meters of the whole paper machine unit.
 
All this puts high pressure on the document production process. The documentation of a paper machine is composed of document components that each describe a small part of the whole machinery and the documents are created by several units within the company, as well as by subcontractors. Each of the document assemblies is unique. The documentation must be maintained over the whole product life cycle that is typically over 20 years. During that time a lot of changes and renovations are made. Yet another dimension to the complexity is added by the fact that Valmet exports its products globally: documents have been translated into more than 20 languages.
 
All this means that the documentation of a whole machinery is composed of hundreds of document components that each may have three kinds of variations: revisions to take care corrections, document translations and document variations describing different product component versions (Figure ). Each document delivered to a customer is an intersection of these three dimensions.

 
Dimensions of document variations

 
 
 

Background
 
The co-operation between Valmet Co. and VTT Information Technology started already in 1995. The main targets of the first phase of the project were :
  • to develop a document type definition on the basis of the document content modelling,
  • to integrate document production into the management system of the product structure,
  • to adopt a unified identification system for the product structure and the documentation, and
  • to make a feasibility study of the integaration of SGML and STEP.
 
As a result of the first project phase a first version of paper machine DTD was produced, the documentation needs were identified, so the documentation can be divided into independent document components and the mechanism for linking these components with corresponding product components was defined. The results of the first phase were promising and the development was continued by starting an integration of the prototype system into the real document production process in the Valmet Winders unit. Winders" new flagship - the WinRoll - was designed so that its structure is easily dividable into independent modules whose documents can be handled separately. Each of the modules was documented separately using the paper machine DTD and the final customer documentation was assembled from the document components. The first full customer documentation produced using the system was delivered to the customers in paper and electronic format in spring 1997.
 
The prototype system that was used to create the first customer deliveries stores the document components as SGML files without using any database capabilities. However, it was early realised that to get the full benefit from SGML documentation an SGML database is needed. at the end of 1996 a European Community research project DOCSTEP was started . The DOCSTEP project aims at integrating standards for product modelling, document management and natural language processing in order to improve the process of document creation and management. The major issue in the DOSTEP project is language engineering, that is to provide methods for e.g. document translation and terminology management.
 
One of the main goals in the DOCSTEP Valmet application is to use of an SGML database for helping the document authoring, translation and publishing processes. To support this goal ways to create a linking mechanism between product structure and documentation were researched and the user interface that enables the users to easily view and manipulate the documentation by navigating in the product structure was developed.
 
 

Valdoc architecture
 
The overall system architecture consists of separate repositories for storing SGML documentation and product structure (Fig ). The core of the system is the product structure navigator, called StepDocs. StepDocs, implemented by VTT information technology, can be used for several purposes:
  • to create graphical view of generic product structure,
  • to select right product components belonging to each customer delivery,
  • to create links between product components and their documents,
  • to retrieve documents for authoring, translation or viewing by selecting corresponding product component, and
  • to collect all the document according to the product configuration for creating document assemblies for publishing. StepDocs cannot directly read data represented in STEP format, but its data structures are designed so that the real the STEP connection can be made in the future.

 
Valdoc system overall architecture

 
 
The StepDocs user interface is used by both the documentation manager, who can create the document configuration with it, and by the technical writers, who use StepDocs as an interface for starting the authoring or translation processes.
 
Even though the name of the product structure navigator is STEPDocs, we do not have a direct interface to any STEP repository. The product structure information is stored in our own file format, which has structured structure using XML-DTD. The file format is so simple that the product data information received from the PDM system is easily transformed to that structure, whether the PDM system understands STEP or not.
 
Storing the documents into an SGML document database enables us to control document element level versioning. SGML database offers also all the standard database service, such as transaction management and, depending on the product, more or less sophisticated query language. Of the commercial products are available for example Astoria

Note:

 
Astoria is a trademark of Chrystal Software, Inc.
and Information Manager

Note:

 
Information Manager is a trademark of Texcel International A.B.
 
 

Product structure
 
The basis of the Valdoc system is the concept product structure, that is a product structure which is not fixed until the customer has selected optional features of the product. The concept product structure is a kind of a general model which includes all the options which the customer can select. It contains all the product components, the relationships between the components in the product hierarchy and other information that can be attached to the components (such as component name, descriptions etc.). The components may have several variations amongst which the customer can choose. In the concept product structure three main types of relationships may be defined between the component: the relationship may be
  • compulsory (the component belongs to every customer configuration),
  • optional (the component may or may not belong to customer configuration), or
  • alternative (one of alternative components belongs to customer configuration).
The concept product structure reminds the generic product structure introduced by Svenberg .
 
In addition to modelling a concept product structure, a way of modelling the customer product configuration was defined. The customer product configuration consists of the selection of the product components, which are delivered to a particular customer (Figure ). In the customer structure, all the product components are compulsory since all the selections are made in the concept product structure.

 
Concept product structure and customer product structure.
 
In the concept product structure the symbol ? stands for an optional relationship and the straggling line represents alternative product components. Overlapping rectangles describe product components that have several variations.

 
 
The Winder is an independent component of whole paper machine unit. One of the Winder types, the Winroll, was designed to be modular and the concept product structure was defined simultaneously with the design process, together by the documentation experts and the design engineers. It was noticed that the task was not as straightforward as could be expected, althoutgh the Winroll was designed to be as modular as possible. The reason was that the concept product structure was defined as mechanical structure of the product. It seems the mechanical designer and e.g. the automation designer see the product component from a different angle. However, a good compromise of the different view was found but it seems, that applying a modelling method based on the product functions might be worth investigating as an additive modeling method .
 
 

Document structure
 
The VALMET DTD is based on the Swedish FMV( Förvarets Material Verket) DTD, and it is strongly content-oriented. The first version of the DTD was designed in 1996 and it has been slightly modified several times. The latest modifications were made at the end of 1997 to ensure compatibility with the XML standard . This DTD is used as an authoring DTD.
 
The DTD has element levels that correspond to the product structure: MODULE element contains information that belongs to one product component, e.g. general safety document elements and terminology used for this product component. MODULE may contain one or more VARIATIONs which contain information belonging to one product variation. The VARIATION element consists of the following main subjects: technical data, structure and functional principles, operating instructions, mechanics, electronics, hydraulics, pneumatics, and automation. It depends on the type and function of a component variation, which of those main subjects are included in the documentation. These subjects and the corresponding DTD elements are called the main DTD branches (Figure )

 
Main levels of the DTD.

 
 
Each of the main branches describe one topic that is documented. E.g. operations instructions illustrated in figure contain author notes (information about the writer(s) of this topic), operation safety instructions, descriptions of each procedure, that is the the component operation and maintenance instructions. Each procedure consists of description of the procedure, preconditions that are needed for the procedure, actions needed to make the procedure and postconditions after the procedure has been conducted. Operation instructions also contain maintenance instructions, which are divided into maintenance that is done periodically and on-demand maintenance and troubleshooting.

 
Example of one of the main branches: operation instructions.

 
 
 

Linking product structure and document structure
 
The linkage between product components and documents is simple: each product component contains document identifiers of the corresponding document elements. The document is found from the SGML database by searching an element whose attribute equals to the document identifier. Basically there is one document identifier per product component linking to a document component representing one DTD branch, that is e.g. to the element containing safety instructions. However, since the documentation attached to the component is dependent of the configuration on the whole, the component cannot contain only one document identifier but a list of them. The customer configuration mechanism is used for selecting the right document identifier belonging to the particular configuration.
 
Since the level in the DTD that is used for editing and translation is always a main DTD branch level, that is the elements describing operating instructions, mechanical, electronic information etc., the links always point to that level. However, the mechanism itself allows linking to an arbitrary element in the DTD.
 
It may be argued that the main DTD branches are too high in the DTD hierarchy to allow an efficient reuse of document components. Our experience is however that the granularity of the document objects to be authored can not be too small, e.g. single paragraphs. If the documentation is assembled from too small pieces, the writing style may change between successive paragraphs, making the document difficult to understand. The same applies to the process of translation: the translator also needs to see the context of the paragraph to be translated. Also it must be noted that creating the linkage to quite a high level in the DTD hierarchy does not hinder the efficient reuse of smaller elements as will be described in the next section.
 
 

Reusing mechanism
 
Studies show that 50 - 70 % of content of technical manuals is repetitious either internally or externally . The same is also noticed in the case of Valmet documentation. One of the most important challenges of the Valmet paper machine customer documentation production is a strong needof reusing document elements. Since the the most product components delivered to the customers are mainly modifications of the existing components, their documents have a great deal of equal structures. The changes may be rather small, e.g. deleting, editing, or adding a few paragraphs. This means that when corrections are made, it would be an extensive task to find all the documents that use the same components if the document components are just copied to several documents, without any reuse mechanism.
 
Translating the documents adds one dimension to the reusing problem. Consider the following real life situation: We have delivered a product with documents in Finnish and English. Another customer wants a slightly modified product and documents associated to it. The new document variant is based on the existing document in Finnish so almost all document elements are the same. Then we want to translate the new variation document into English. Since we already have the translation of the original document in English we only need to translate the deviating document elements. The problem is that finding the already translated document elements might be an enormous task to do. This, of course, increases the translation costs.
 
To address both the problems described above we store the paper machine documentation into an SGML document database and heavily take advantage of the database document element reusing mechanism, henceforth referred to as element sharing.
 
Element sharing in an SGML document database means that any document element stored in the database can be used in several documents. We call a sharing element an element that is not physically stored in the database. Instead , only the pointers to the element in another document, the shared element, are stored. The same element can be shared by many elements and they all are updated simultaneously by changing the shared element. This means that corrections can be made by correcting only the shared element and the correction is mirrored automatically in the sharing elements.
 
To solve both the reuse of document elements and reuse of translations, paper machine documents are stored in the SGML database, so every leaf level element in the authoring DTD is in the SGML database replaced by a container that holds elements of different languages. The language of the element content is indicated with an attribute. This structure is used only for database storage purposes. When the document is checked out from the database for editing or publishing, only the elements with the specified language are selected. The figure illustrates the structure of the database document.

 
Storage structure of a document stored in the SGML database.

 
 
The main advantage of the document storage structure is achieved when combined with SGML document database sharing mechanism. The author creates a new document component variation by checking out an existing database document component into an SGML editor. This document functions as a base document. The author modifies the base document by editing, adding or deleting elements.
 
Once the work is finished the new variation document is stored into the database, so those elements of the base document that remain untouched are automatically shared in the database. But instead of sharing only paragraph elements we share the whole container containing all the translations of the element. After that all the sharing containers in the new document variant share not only the paragraph but all the earlier made translations too as illustrated in figure .

 
Reusing the translated elements by sharing the element container

 
 
The sharing mechanisms implemented in the SGML databases seem to rely heavily on user interaction: the user manually selects all the elements that she wants to share. We have taken another approach, we try to find all the elements that are equal in the base document and the new variation document and automatically share all these. We have used a commercial SGML differencing program to find the similar components. It seems that the program can find almost all equal components, but extensive differences in the structure may cause the program to omit some components that could be shared.
 
The idea of sharing all the translations in the same container is based on the assumption that all the translations share the same structure. This can well be assumed when translating technical documents. However, to assure that the translator does not change the structure, a special SGML translation editor application is used. The translation editor creates, using the translation source document, a target structure having the #PCDATA elements with no content (Figure ). The structures are presented in adjacent windows in the translator editor so that scrolling in one structure causes the other structure scroll synchronously. The translator writes the translation of the element into the corresponding element in the target structure.

 
Translation of the database document.

 
 
The translation editor can also have two structures as input: the source language structure and the target structure, in which some #PCDATA elements are already filled in, in case the corresponding translations are already found in the database. The benefit of reusing the translated elements appears when we translate the document sharing element containers. When the new variation document is checked out from the database the translated elements can automatically be included in the target structure (Figure ).

 
Reusing the translated element in the translation editor.
 
The English paragraph in the shared element container is automatically inserted into the target structure in translation editor.

 
 
 

Conclusions
 
We believe that integration of product structure and structured documentation can solve a great deal of problems of managing technical documents of complicated products. We do suggest that the document management and product management should be separated, however, letting the product structure to be used as linking mechanism. Design information produced by the product design engineer should be managed within the product model, e.g. using SGML_STRING approach but actual customer documentation management is most easily done by using SGML tools.
 
The project has shown that it may be quite difficult to create a such concept product structure of a complicated product that correctly represent the product from all the viewpoints, such as automation and mechanics. It seems possible to create a such view to product structure that meets the documentation needs. Even better results could possible be achieved if functional view to the product was adopted in addition to a mechanical structure.
 
The system described is based on existing commercial tools, with the exception StepDocs user interface tool. The system described is not based on the features of any particular tools, but we have tried to build it as tool-independent as possible. We have also been able to create an SGML based documentation environment step by step, using a system based on simple SGML file strategy on first customer deliveries, and going towards a full SGML database environment in the near future. The Valdoc system is already partly in production us, but it is still heavily developed.
 
An aspect of the document management system that was not included in this paper is control of the document quality. We are currently developing methods for controlling quality of language and terminology used in the documents, but results of this research are left to future publications.
 
Bibliography
Reschke96
Reschke, R. and Tucker, H., Configuration Control for Product Documentation, (A Way of Integrating STEP & SGML, 0.4). August 31. 1996. Available at http://www.eccnet.com/step/White_Paper/.
Tucker97
Tucker, H. and Harvey B., SGML Documentation Objects within the STEP Environment. In Proceedings of SGML/XML '97 Conference, Washington, USA, December 8-11, pages 205-211, Graphic Communications Association, 1997.
SWEDCALS95
Wenzel, B., Bergstöm P.,Magnusson, S. J., Andersson, U., Tucker, H., Holm, T., Haara, E., Lindström, S., Interoperatility between STEP and SGML. White paper, November 1995, Swedish Association for CALS (SWEDCALS).
Elovainio96
Elovainio, K., Document Management by Product Models. In Proceedings of SGML '96 Europe Conference, Munich, Germany, May 12-16, pages 69-78, Graphic Communications Association, 1996.
Elovainio97
Elovainio, K. and Kuntz, J., SGML DOCSTEP - Technical Documentation Management Using STEP. In Proceedings of SGML '97 Europe Conference, Barcelona, Spain, May 13-15, pages 43-53, Graphic Communications Association, 1997.
Kaarela95
Kaarela K., Oksanen J., Takalo J.,An Information Model as a Basis for Hypermedia-Based Plant Documentation. Computer Networks and ISDN Systems 27(6): 751-764 ,1995.
Svenberg97
Svenberg S., Intention-based Input Specifications for Automated Document Generation. In Proceedings of SGML/XML '97 Conference, Washington, USA, December 8-11, pages 417-426, Graphic Communications Association, 1997.
Nicholson97
Nicholson S.,The Need for Component Methodologies in Global Applications. In Proceedings of SGML/XML '97 Conference, Washington, USA, December 8-11, pages 241-247, Graphic Communications Association, 1997.
XML
Extensible Markup Language Version 1.0, World Wide Web Consortium Recommendation, February 10, 1998.
IM97
Information Manager Reference Guide. June 1997, Texcel N.V.
Imposing Intelligence on Graphics: Using HyTime Hyperlinks with Non-SGML Data   Table of contents   Indexes   Plato, SGML and revolution