Documenting with PI-Mod

The introduction of an XML-based documentation system requires multifaceted planning and far-reaching decisions. To give an example, the selection and introduction of special content management systems for technical editing was described in detail in the tekom CMS studies of 2005 and 2008 [1]. As well as IT project management, these studies explain the preparatory planning work that has to be performed within the company. This work can be summarized under the term "content engineering" and contains decisions on the structuring of information, on modularization and variant management, and on rules on phrasing and formatting. Such rules have to be developed or introduced on the basis of standards.

The selection of a suitable information model is particularly important for XML applications because it maps most of the specified rules. The XML structure elements it contains provide the structural grid for the entry of text. Phrasing samples and, ultimately, the options for publication are coupled to the information model and must be adapted to the requirements of the respective type of information.


No consistent model so far

In spite of efforts to achieve standardization, there is no established consistent (XML) information model that meets all the needs of structured information gathering. Differences between the structures for possible types of information, products and target groups seem too great. The 2008 study also showed that around half of all documentation was drawn up without actual structuring or modeling at that time. Around a quarter was created with structures specific to a company or system. The remainder in the German-speaking area was shared evenly between several standardized and public (XML) information models such as DocBook, DITA and S1000D. CMS providers also usually provide system-specific information models. These models come from customer projects and have been optimized over the years for use in the respective systems.

With the exception of larger companies, XML applications are still in the minority when it comes to editorial tools and systems. However, interest in such applications seems to be growing, especially in small and medium-sized businesses. A new internal method for structuring information ought to be tackled at the same time.

Existing standardized information models come from specific industries and applications such as software documentation or documentation in aviation or the military [2]. No information model has been established as a standard or quasi-standard for plant construction and mechanical engineering and the user and service information involved. In the past, the majority of CMS projects in the German-speaking area was implemented in exactly this environment or related areas, usually as system-specific implementations or individual solutions. Unfortunately, the attempt of the VDMA to establish the "mumasy" information model did not have a widespread impact.

The concept

It therefore seemed appropriate to define a structure based on the experience gained in mechanical engineering that could be of general use as an open information model. One of the mentors was the structure of the LIEBHERR Group, which has been in operational use since 1997. In 2008, several companies and consultants defined the new "PI-Mod" information model in real projects under the general management of Prof. Ziegler. This model allows contents to be entered in modular fashion - hence the "Mod" part of the name - in broad areas of plant construction and mechanical engineering as well as in related industries (automation, electronics, consumer products).

One very important goal was to provide a structure that would be easy for CMS providers to implement. For example, it was necessary to keep implementation details "open" in those places, which empirically are implemented differently in every system; examples include mechanisms for cross-reference and reuse. At the same time, the intention was to cover in particular the specifics of the industry, i.e. the information structures typically required there. These are included by means of semantic elements, i.e. structures such as technical data or maintenance plan information that are named according to their function and application.

Product and information qualification

The "PI" in the name is used not only for its association with a "circular" method of documentation, but primarily for a classification of modular contents that is necessary in practice. During module planning or content engineering, meta data are allocated to the modules in order to enable them to be stored and found. In addition, the intention is to enable further processing of publications and information. Meta data usually map the product classification ("P") and information classification ("I"). The corresponding XML attributes in the modules are therefore named "prodclass" and "infoclass". Like in many design-based classification schemas for components or their product or function structures, these attributes can be applied hierarchically in order to map interdependent meta data.

The same applies to the classification of information types. The multi-level meta data of the information classes often result from the normative structuring of operating manuals and the specifications from the Machine Directive. The abbreviated version of the method of "PI classification" used here is independent of any specific information model and is suitable for general use in editorial systems [3]. The following table contains typical examples of PI classifications in different modules. Module 1 contains the composition description for an inking roller in a company-specific partial hierarchy, while module 3 contains the assembly instructions for a longitudinal cutter.

As every CMS project - or, to be more precise, every product and every industry - requires different meta data values, these are not part of the PI-Mod standard as a whole, but are instead created as respective company-specific values ("customizing"). Providers and implementers of systems have extensive experience in this area, and this experience can be suitably implemented here.The classification of the information to be recorded is also reflected in the descriptive names of root elements of modules. In total, the current information model contains seven module types, which are depicted in figure 1. The uppermost level of information-related meta data therefore corresponds to the module types in the example. PI-Mod uses English terms such as "descriptive".

Fig. 2: Seven module types in PI-Mod; the mod element serves as brackets for the module types.

PI-Mod takes into account the "classic" descriptive and instructional information recorded in the two main module types:

• descriptive, which is used, among others, for composition and function descriptions, technical data and general descriptions
• task, which is used for instructions for individual steps

In addition, there are five more module types that accommodate the specific requirements of the industries mentioned:

• diagnosis, for simple troubleshooting
• taskintervals, for maintenance plans
• tools, for tool lists and operating equipment
• lubrication, for lubrication plans
• glossary, for glossaries

Every module type has its own, functionally motivated sub-structure, which is largely formulated semantically, i.e. using descriptive element names. This means PI-Mod can be combined with structuring methods such as function design and language control tools. Modules can then be used to fill specific publication structures. Instead of providing a specific aggregation structure and fixed referencing mechanisms, the standard provides the numerous system-specific freedoms required. This is exactly the point where the working methods of CMS differ greatly. However, due to the uncomplicated hierarchical interlocking of modules, PI-Mod makes it possible to use a multi-level publication structure that is suitable for a great many document types. The modular approach and meta data structure also allows other applications to be implemented, such as portal access to component information or other mobile and electronic applications.

Special mechanisms

The model also offers further special features, including the "collections mechanism" and the tagging of technical or physical parameters as numerical values and units. The latter allows the automatic conversion of tagged units from metric to imperial, for use in the US, for example, or vice versa. It is also possible to enter both systems of units and process them manually or filter them by market. All these options occur in practice, so they should be supported by an information model and its implementation.

The collections mechanism is also designed to be suitable in practice. It is, for example, possible to provide information on the frequency and responsibility relating to maintenance tasks within the task module, and using the taskinterval semantic element. This information is gathered automatically during publication and then output as a structured maintenance plan – figure 2.

Fig. 3: Schematic illustration of the automated publication of maintenance tables by means of the collections mechanism - maintenance intervals are recorded in the task module with the taskinterval XML element and then collated for publication in the taskinterval module; bottom: maintenance table in a PI-Mod implementation, sorted according to components.

Conversely, it is also possible to record custom taskinterval modules separately as a part or as complete maintenance plans. Next to the semantic structures, it is also possible to use manually-entered tables. This also makes it possible to use a mixture of various working methods in the content management environment. The recording and publication of tool lists and working materials (tools) or lubricants (lubrication) is organized according to the same principle.

The remaining module types, "diagnosis" and "glossary", are designed for troubleshooting and error tables (messages, causes, remedies) and for glossary entries and overviews in publications.

Adjustments

Even though PI-Mod was developed as a standardized information model, its design and technical implementation allow for additional customizing options. That is why the PI-Mod packages for DTD and style sheets consist of a central "core" and a "custom" part. The core provides the structures, elements and attributes defined as the technical core. These are used in the custom DTD to provide a best-practice project implementation that is capable of running in the standard. Where necessary, it can be customized flexibly by means of a simple overwriting, deleting or creating mechanism.

Thanks to the separation between PI-Mod concepts and implementation logics, it is possible to consider and implement customer and system-specific requirements. The procedure for customizing was defined methodically and documented comprehensively. It is possible, for example, to integrate additional standard features from newer versions of PI-Mod in current projects in spite of any adjustments made [4].

Tools and services

PI-Mod was quickly met with interest by CMS providers and users. From 2008, it was implemented in the first live projects and provided the basis for the current version 1.2. This is available on the internet as an open-source application.

• The PI-Mod information model as document type definition, DTD
• The element reference can be used as part of an editorial guideline
• Style sheets for the formats XSL-FO/PDF, CHM, HTML
• The documentation of the methodical PI-Mod customization
• An environment for XMetaL

The website also contains a current overview of content management systems that provide PI-Mod as standard or as an extension. The information model can be used free of charge and is only subject to one license which must contain a reference to the source. Service providers and providers of CMS can perform their own customizations or implementations independently from the PI-Mod working group. This will allow consultation on the use of PI-Mod to be offered as a service in future. As is usual for free projects, the working group is based on feedback, and on support from users and interested persons.

Conclusion and outlook

Until now, the reaction to the information model has been positive, even though it is still in its initial stages. However, acceptance at well-known companies such as ABB STOTZ KONTAKT and Koenig & Bauer shows that the benefits of a standardized information model are convincing: a fast and cost-effective implementation of methodical and technically tried-and-tested structures. The long-standing desire in mechanical engineering of allowing data exchanges between companies in the supply chain can be met in technical terms with such concepts and information models.

Further developments are requested and planned for the (mechatronic) coupling of existing documentation with machine-linked software and control components as well as for training documents. Software documentation as supported by the DITA implementation is not a focus of PI-Mod. These two information models actually complement one another.

The PI-Mod developers have so far not favored applications without CMS, as both methodical (PI classification) and technical knowledge (XML/XSL) is required, and this is only available in individual cases in the target industries. However, in many cases it is possible and sensible to test the modular and XML-based documentation in terms of a "proof of concept" under supervision prior to the introduction of a CMS. PI-Mod provides the entry and publication options required for this purpose. Additional editor support is being prepared, including for Adobe InDesign. Further organizational design is still open. Different concepts are possible for the long term; the structure could be maintained by a consortium or an association, for example. In general, the principle is that cautious technical development is preferable to marketing-driven hype.

Bibliography

[1] Straub D., Ziegler W. (2008): Effizientes Informationsmanagement durch spezielle Content-Management-Systeme. (Efficient information management through special content management systems)

[2] Krüger M., Ziegler W. (2009): Standards für strukturierte technische Informationen – Ein Überblick. tekom Hochschulschriften, Bd. 16. (Standards for structured technical information - an overview. tekom academic journals, vol. 16.)

[3] Drewer P., Ziegler W. (2010): Technische Dokumentation – Eine Einführung in die übersetzungsgerechte Texterstellung und in das Content Management. (Technical documentation - an introduction to creating texts suitable for translation and to content management.) Vogel Verlag.

[4] Steurer S., Ziegler W. (2010): PI-Mod in der Praxis – Einsatz und Anpassung des Informationsmodells für das Content-Management. (PI-Mod in practice - using and customizing the information model for content management) Conference transcript, tekom annual conference.