Knowledge-based Configuration: From Research to Business Cases, FIRST EDITION (2014)

Part IV. Case Studies

Chapter 20. Configuring and Generating Technical Documents

Rick Rabiser^a, Michael Vierhauser^b, Martin Lehofer^b, Paul Grünbacher^a and Tomi Männistö^c, ^aJohannes Kepler University Linz, Linz, Austria, ^bSiemens VAI Metals Technologies, Linz, Austria, ^cAalto University, Aalto, Finland

Abstract

In industrial software development salespeople, product managers, or technical writers frequently create documents such as offers, contracts, user manuals, or technical documentation. For products that are configured specifically for different customers, the documentation also needs to be adapted to match the product. Such adaptation of documents is tedious and error-prone and can easily lead to inconsistencies. Stakeholders thus need configuration support for adapting documents. We describe a flexible approach for automatically generating product-specific documents based on product line variability models. We report on an industrial case example of applying the approach to support configuring and generating product-specific documents in an automation software product line.

Keywords

Knowledge-based Configuration; Software Product Lines; Variability Modeling; Product Derivation; Document Generation; Tool Support

Acknowledgments

This work has been funded by the Christian Doppler Forschungsgesellschaft, Austria. The authors would like to thank Cornelia Miesbauer for her work on the MS Word add-in and generator.

20.1 Introduction

Software product lines aim at providing the means for dealing with variability in large software systems effectively to leverage extensive reuse (Pohl et al., 2005; van der Linden et al., 2007). Software product line engineering (SPLE) covers activities such as domain scoping, modeling the variability of reusable artifacts, configuring and deriving individual products, and managing evolution. The tasks for a particular product line typically include the development of a common platform, the definition of the product line’s architecture, and the automated configuration and derivation of product artifacts.

In this chapter, we focus on the derivation of individual products and related artifacts such as product-specific documentation. More specifically, we address a particular type of derivation: automated product configuration and artifact generation. The automation is based on a predesigned model that describes system variability accurately enough so that all desired variants can be derived from the product line. This principal goal makes product configuration (see Hotz et al., 2014a¹) perhaps the most modeling-intensive of all SPLE tasks and thus sets high requirements for the rigor of the modeling methods that need clear enough semantics to support the automation. This can be achieved, for example, by mapping the variability modeling concepts to a logical representation with formal semantics or a powerful enough decision support system (Asikainen et al., 2007; Benavides et al., 2010; Dhungana et al., 2011; Hotz et al., 2006). Given such a conceptualization, appropriate tools (see Leitner et al., 2014²), such as inference engines, can be used in the configuration task to search for valid configurations. Researchers and practitioners in the realm of product configuration are typically adopting feature models (Asikainen et al., 2007; Benavides et al., 2010), component connection models (Asikainen et al., 2007; van Ommering et al., 2000), decision models (Dhungana et al., 2011), or other approaches (Pohl et al., 2005; van der Linden et al., 2007) to define variability. Many methods and tools for configuration in SPLE are similar to those in the knowledge-based configuration community (Soininen et al., 1998; Stumptner, 1997); also see Hotz et al. (2014a).

Model-based product configuration involves three main activities: (1) the definition of variability models, (2) the actual configuration task of producing a description for a valid configuration, and (3) the generation of product artifacts on the basis of the produced configuration description. Variability modeling for product configuration is demanding and costly as all possible variations need to be captured. The modeling method and tool support are often tightly connected as the semantics of the modeling concepts heavily reflect the possible tool support. During configuration, configurers select from the available variability, for example, by choosing features (see Hotz et al., 2014b³). They rely on tool support for finding an appropriate configuration (see Leitner et al., 2014⁴). The output of the configuration task is a configuration description that includes a list of the selected features. Generation then uses the configuration description for creating the actual product and related artifacts for the particular configuration. Generation can be separated from the configuration task. For example, in the knowledge-based community, where the configured artifacts typically are manufactured products, manufacturing is inherently a separate activity from configuration. However, in SPLE artifact creation can often be done with the same machinery as the configuration task, such as, a computer, improving the potential for integration of configuration and generation tasks.

In the following, we first provide an outline of defining a model-based product line for supporting configuration and generation of arbitrary artifacts in SPLE and then present an industrial case example on supporting the generation of user documentation in an automation software product line. We discuss how document variability can be modeled; we present tool extensions for managing and configuring documents in a software product line; and we show how configuring and generating documents is supported in our industrial example.

20.2 Defining Model-Based Product Lines

Several tasks are performed in SPLE when defining a model-based product line for supporting the configuration and generation of arbitrary artifacts.

Analyzing variability in artifacts. An industrial product line rarely starts from scratch. Product line experts familiar with a system’s variability thus typically first examine existing artifacts such as user manuals or code. The analysis shows what can vary (the variation points) and how it can vary (the variants). It is challenging to find the right level of detail and granularity that is needed to distinguish products. Workshops conducted with domain experts from product management, sales, and development help to ensure focus.

Defining variability models. The product line experts use the collected information to define variability models using an approach and tool of their choice. This task involves defining variability that allows distinguishing the different products of a product line, for example, represented as selectable product features or configuration decisions. It also means modeling the relation of reusable artifacts to features or decisions. For instance, the selection of a feature in product configuration might require the inclusion of a particular software component and a related document in a configured product.

Preparing artifacts and devising domain-specific generators. Model-based product line approaches rely on generators to automate the creation of product-specific artifacts according to a configuration description. Generators typically exploit variation points in the artifacts. For example, code and document formats can be extended using annotations, markups, or placeholders that can be used to tag variable parts that need to be substituted or modified later on. Therefore, generators need to be developed that use the choices made by the configurers during product configuration (e.g., the selected features) to compose and adapt the reusable artifacts for a specific product. Depending on the nature of a product line and its characteristics, different types of artifacts need to be supported at different levels of granularity. Generators can be developed to create parts of a system’s source code, configuration files for parameterizing a system, or high-level artifacts such as user documentations or product descriptions. Generators help to reduce the time-consuming and error-prone manual adoption of product artifacts. They are commonly developed as extensions to existing product line (configuration) tools.

Augmenting the artifacts with variability information. Product line experts rigorously specify the variation points and variants in the artifacts and relate them to the variability models using the chosen variability mechanism. During product configuration generators can resolve the variation points based on the user choices in the configuration description to produce product-specific artifacts.

20.3 Industrial Case Example: Customizing Technical Documentation

SPLE traditionally has a strong focus on program artifacts such as code or configuration files. However, in practice configuring documents is a very frequent and crucial use case. Sales people, marketing staff, or product managers prepare customer-specific documents such as offers, user manuals, or contracts. Industrial experience shows while the configuration of products is often at least partly automated, documents are typically still adapted manually. For instance, at Siemens VAI the manual adaptation of documentation for the CC-L2 product line (see later) for each customer is tedious due to the size of the document (hundreds of pages). Furthermore, inconsistencies between the provided documentation and the deployed software need to be avoided.

In our industrial case example we modeled document variability and applied model-driven SPLE to structured documents. Our approach is generic and flexible to automate document generation independently of the concrete type of documents and regardless of the maturity of the product line, the degree to which variability modeling and generative techniques are already applied. We have originally described the approach in Rabiser et al. (2010). Since then, it has been extended with generators for Microsoft Word documents and applied in a number of industrial product lines. Our approach is based on the model-driven SPLE approach DOPLER (Dhungana et al., 2011) and supports generating both deliverable documents and software systems from the same variability model. This is feasible as many decisions made during product configuration are relevant to both types of artifacts. For example, the decision to include a certain feature often also requires the inclusion of the user documentation of this feature.

Using DOPLER we applied our approach to Siemens VAI’s CC-L2 product line for process automation of continuous casting machines in steel plants. Examples for variability in this product line are the number of strands, the choice of whether to include a cooling system, and the type of cooling. Such variability not only affects technical software assets but also directly shapes the user documentation of the software. Our goal thus has been to automate the generation of customer-specific technical user documentation based on existing variability models created for software configuration. The component-based architecture of this software is based on Java Beans and the Spring component framework. CC-L2’s variability had already been modeled for the technical software artifacts (Dhungana et al., 2011) when we started developing support for configuring documents.

20.4 Modeling Document Variability

We started with analyzing variability in documents by interviewing domain experts to reveal the most relevant variability patterns. We additionally analyzed the technical user documentation as well as sales documents for several systems in the domain of industrial automation systems and identified the following common patterns of document variability:

• Placeholders in documents are replaced with product-specific text or calculated values during configuration. Customer or system details, prices of features, or the total price of all included features have to be filled into documents directly based on the configurers’ choices or by computing values based on the choices made (Lettner et al., 2011).

• Optional text is added or removed in documents depending on choices regarding the features to be delivered. For example, sections documenting a particular cooling strategy are not part of the document if this feature will not be deployed.

• Alternative text (e.g., chapters or sections, paragraphs, sentences, or even words or letters in documents) is defined based on the choices made in product configuration, for instance, to reflect the choice for an operating system or a database.

• Cross references linking elements within documents or referring to external documents must be updated appropriately. For instance, the main index and figure and table indices must be modified based on the included text.

• Simple grammatical variability mainly pertains to singular versus plural (e.g., single hard disc vs. multiple hard discs) or gender.

• Images have to be included, for example, to describe the user interface of the delivered system.

• Formatting and layout pertains to different styles that are needed for different customers.

We used the DOPLER approach (Dhungana et al., 2011) to model document variability. The approach comprises a variability modeling tool and a configuration wizard to present variability to users during product configuration. Engineers create domain-specific meta-models to define their Asset types, attributes, and dependencies (see Figure 20.1).

FIGURE 20.1 Extended DOPLER meta-model with Chapter, Subchapter, Process, and Component Asset Types for modeling the CC-L2 system. The figure also depicts how elements from the meta-model are used to support configuring and generating variable documents; i.e., Decisions are used to customize documents (e.g., to fill placeholders) and Assets are used to select documents or parts thereof (e.g., a particular chapter).

In DOPLER variability models Decision entities are used to distinguish different products in a product line. Important attributes of a Decision are a unique id, a question that is asked to a user during configuration, and a Decision type (Boolean, enumeration, string, or number). A Decision can depend on other Decisions hierarchically (if it needs to be made before other Decisions) or logically (if making the Decision changes the answers of other Decisions or if Decisions mutually exclude each other). The range of possible answers defined by the Decision type can be further constrained with validity conditions. Assets represent the core product line artifacts such as technical components or documents. They can depend on each other functionally (e.g., one component requires another component) or structurally (e.g., a subchapter is part of a chapter). Assets are linked to Decisions via inclusion conditions defining when a particular Asset is included in a configured product. Asset attributes can also depend on answers to Decisions to enable the customization of Assets.

Figure 20.1 shows the meta-model for the CC-L2 variability model with the predefined elements Decision and Asset. The CC-L2 specific Asset types are Chapter (representing a chapter of a document), Subchapter (representing a part of a chapter), Component(representing a software component), and Process (representing virtual machines executing software components). The elements Chapter and Component have an attribute location of type URL in addition to the default model attributes id and description. A Component is described in a Chapter or Subchapter and a Process is described in a Subchapter to link technical components with document Assets. A Subchapter can be part of a Chapter.

The Asset types Chapter and Subchapter are used to model coarse-grained variability. Explicitly representing parts of documents as Assets in a model provides an additional level of abstraction for defining document variability and for selecting particular chapters or sections. While it would also be possible to describe document variability only at the level of Decisions we have learned that this additional level of abstraction helps domain experts to better understand coarse-grained variability of documents. This level of abstraction additionally reflects the component-based architecture of the system. Different components or subsystems are developed by different teams and therefore also the documentation is maintained by different people at different locations. For example, the Chapter WebHMI represents the documentation of the web-based human-machine interface of the CC-L2 system and depends on the Decision “Do you need the Web HMI?” (see Figure 20.3). If a user selects this feature, the required Components are included in the configured product. Due to the described in relation to the Chapter WebHMI, this Asset is also included in the configured product. The same Decision can often be used for several chapters or for including both chapters and components thus making the approach more flexible.

In about two thirds of the cases we could use configuration decisions already defined in the existing variability models (Dhungana et al., 2011) to provide support for documents in the CC-L2 variability model. In the remaining cases we added new Decisions specifically for document generation. The variability model for the CC-L2 system defines 18 Decisions (each providing between 2 and 11 choices), 33 component Assets (selected based on Decisions), 31 process Assets (selected based on Decisions), 13 chapter Assets (included based on selected components), and 180 subchapter Assets representing text sections (included based on selected components and/or processes). Several dependencies are defined among Decisions, Assets, and between Assets and Decisions to reflect the technical dependencies of the CC-L2 system, to guide the user in product configuration, and to allow selecting and parameterizing Assets based on the configurers’ decisions.

20.5 Tool Support for Document Configuration and Generation

Figure 20.2 shows the tool architecture of our approach. Product line engineers use a modeling tool (i.e., DOPLER) to define the variability of components and documents. They augment documents (i.e., Microsoft Word files) with variability information and link them to the variability model. Domain experts use a product configuration tool (i.e., the DOPLER configuration wizard) including a document generator extension to derive customized documents in product configuration. The resulting tool chain supports modeling the variability of the software and the documents in an integrated manner and automates the generation of both product configurations and technical user documentation using a single decision model.

FIGURE 20.2 Architecture for managing and configuring documents in a product line.

The variability mechanism we developed to annotate Microsoft Word documents with variability information is based on linking texts, tables, or figures with Decisions and Assets. We developed an add-in that allows marking variable parts in documents using Word’s commenting feature. Our add-in is integrated in Microsoft Word’s user interface and allows users to mark and link text, figures, or tables with variability model elements like Decisions and Chapter and Subchapter Assets. Whenever the inclusion or deletion of a text, figure, table, and such depends on a variability model element the user marks the respective text in Word and the plugin automatically creates a comment containing a simple expression that maps the text to the variability model. For instance, the command #text.visible{A:WebHMI} means that the marked text is only visible if the WebHMI Asset is part of the configured product. The command #doc.insert refers to a Word file and is used to insert a whole document into another document. For instance, the command #doc.insert (chapter_Oracle10) {D:dbversion=oracle10} inserts a document explaining the setup of the Oracle 10 database if this version is selected via the Decision dbversion. Variability within tables is enabled via the commands #table.row.visible and#table.col.visible. These commands are frequently used when defining configuration parameters, which are typically documented in tables. For example, #table.row.visible{A:WebHMI} is used to tag table rows that provide information on the default users for the WebHMI system.

We extended the DOPLER configuration wizard (see Figure 20.3) with a generator that uses the configuration description (i.e., the answers to Decisions and the included Chapter and Subchapter Assets) to compose Microsoft Word documents. The generator uses a template of the document to be generated and an arbitrary number of document fragments to be inserted depending on Decisions. The document template serves as the entry point for the generator and contains the table of contents, indices of figures and tables, and the document structure including the comments for document insertions. The various subchapters (represented as fragments) can be inserted on arbitrary positions within the document template. During generation the document template is parsed and the inserted tags are resolved based on the configuration decisions and selected assets. After composing the document, the indices, tables and cross-references are updated.

FIGURE 20.3 The DOPLER configuration wizard shows Decisions and Assets of the CC-L2 variability model. End users make configuration decisions by answering questions. Based on the configurers’ answers to questions, the tool computes the required list of Document Assets for the configured product. The generator then creates customized documents in Microsoft Word format based on this list.

The approach presented in this chapter is currently used within more than 15 product lines at Siemens VAI by nearly 100 users worldwide. While the presented CC-L2 example is combining both the generation of software artifacts and documents, in other Siemens VAI product lines, the usage is focusing on the configuration and generation of documents and also includes the calculation of roughly estimated costs, return on investment, and payback periods. These documents are used by accountants to provide information to customers or to prepare for customer meetings.

20.6 Conclusion

This chapter reported on an industrial example to develop a flexible configuration tool with a focus on generating documents. The approach is based on variability models defining the structure of documents and processing configuration descriptions defining end-user choices. We implemented the approach using the SPLE tool suite DOPLER and Microsoft Word. Our approach is flexible with regard to document types and types of variability. The questionnaire-like structure of DOPLER decision models supports configuration by end users in a configuration wizard.

For the described Siemens VAI’s CC-L2 product line various documents are required, which can now be automatically generated during product configuration with the DOPLER tool suite. The supported document types (e.g., system documentation, user manuals) vary in size and complexity. Although the initial effort for defining markups and models was considerable, the resulting solution was highly appreciated in the company as it avoids the time-consuming and error-prone task of manually adapting documentation. The acceptance of the approach also relies on the use of word processing tools already well established in the company. Furthermore, the knowledge needed for the preparation of product-specific documents is now explicitly defined. This allows more people less familiar with the system to generate valid customized documents and thus reduces the workload of experts.

References

1. Asikainen T, Männistö T, Soininen T. Kumbang: a domain ontology for modelling variability in software product families. Advanced Engineering Informatics. 2007;21(1):23–40.

2. Benavides D, Segura S, Ruiz-Cortés A. Automated analysis of feature models 20 years later: a literature review. Information Systems. 2010;35(6):615–636.

3. Dhungana D, Grünbacher P, Rabiser R. The DOPLER meta-tool for decision-oriented variability modeling: a multiple case study. Automated Software Engineering. 2011;18(1):77–114.

4. Hotz L, Wolter K, Krebs T, et al. Configuration in Industrial Product Families - The ConIPF Methodology. Berlin: IOS Press; 2006.

5. Hotz L, Felfernig A, Günter A, Tiihonen J. A short history of configuration technologies. In: Felfernig A, Hotz L, Bagley C, Tiihonen J, eds. Knowledge-based Configuration – From Research to Business Cases. Waltham, MA: Morgan Kaufmann Publishers; 2014a:9–19. (Chapter 2).

6. Hotz L, Felfernig A, Stumptner M, Ryabokon A, Bagley C, Wolter K. Configuration knowledge representation and reasoning. In: Felfernig A, Hotz L, Bagley C, Tiihonen J, eds. Knowledge-based Configuration – From Research to Business Cases. Waltham, MA: Morgan Kaufmann Publishers; 2014b:41–72. (Chapter 6).

7. Leitner G, Felfernig A, Blazek P, Reinfrank F, Ninaus G. User interfaces for configuration environments. In: Felfernig A, Hotz L, Bagley C, Tiihonen J, eds. Knowledge-based Configuration – From Research to Business Cases. Waltham, MA: Morgan Kaufmann Publishers; 2014:89–106. (Chapter 8).

8. Lettner D, Thaller D, Vierhauser M, Rabiser R, Grünbacher P, Heider W. Supporting business calculations in a product line engineering tool suite. In: MAPLE/SCALE Workshop at Software Product Lines Conference (SPLC), Munich. ACM 2011; Paper number 26.

9. Pohl K, Böckle G, van der Linden FJ. Software Product Line Engineering: Foundations, Principles and Techniques. Secaucus, NJ: Springer; 2005.

10. Rabiser R, Heider W, Elsner C, Lehofer M, Grünbacher P, Schwanninger C. A flexible approach for generating product-specific documents in product lines. In: Bosch J, Lee J, eds. 14th International Software Product Line Conference. Berlin: Springer; 2010:47–61. Lecture Notes in Computer Science vol. 6287.

11. Soininen T, Tiihonen J, Männistö T, Sulonen R. Towards a general ontology of configuration. Artificial Intelligence for Engineering Design, Analysis and Manufacturing (AI EDAM). 1998;12(4):357–372.

12. Stumptner M. An overview of knowledge-based configuration. AI Communications. 1997;10(2):111–126.

13. van der Linden FJ, Schmid K, Rommes E. Software Product Lines in Action: The Best Industrial Practice in Product Line Engineering. Secaucus, NJ: Springer; 2007.

14. van Ommering RC, van der Linden F, Kramer J, Magee J. The Koala component model for consumer electronics software. IEEE Computer. 2000;33(3):78–85.