Component documentation—a key issue in software product lines

https://doi.org/10.1016/j.infsof.2003.10.004Get rights and content

Abstract

Product lines embody a strategic reuse of both intellectual effort and existing artefacts, such as software architectures and components. Third-party components are increasingly being used in product line based software engineering, in which case the integration is controlled by the product line architecture. However, the software integrators have difficulties in finding out the capabilities of components, because components are not documented in a standard way. Documentation is often the only way of assessing the applicability, credibility and quality of a third-party component.

Our contribution is a standard documentation pattern for software components. The pattern provides guidelines and structure for component documentation and ensures the quality of documentation. The pattern has been validated by applying and analysing it in practice.

Introduction

Third-party software components, generic or partially tailored, are increasingly used in software product lines. Modern software systems are thus based on integrated components. A software product line is a collection or family of software systems with similar or overlapping functionality and a common architecture that satisfies the mission requirements for that set of systems [23]. The idea behind product line based software development is to provide a reuse infrastructure that supports a family of products, and to spend the resources in such a way that a high return on investment and reduced time-to-market can be achieved.

The owners of software product lines can be considered as the buyers of components, i.e. integrators, which build products by integrating components. The sellers of software components are component providers, such as software subcontractors, Original software Component Manufacturing (OCM) providers or tailored platform sellers. Third-party components can be classified into Commercial Off-The-Shelf (COTS) components, OCM components, Modified Off-The-Shelf (MOTS) components and Open Source (OS) components. COTS components are ready-made components and are bought ‘as such’, whereas MOTS components are tailored to buyer-specific purposes by the component vendor. OCM components are developed in collaboration with the component integrator and the provider, when the component is adapted to the product line by the component integrator [30]. OS components are offered as free source components [25].

Third-party components, such as databases, protocol stacks, graphical user interfaces and middleware products, can represent an important part of the core assets of a software product line. Documentation of the core assets, such as the product line architecture and its components, has a great importance within product lines, because the core assets must be understood by all stakeholders involved in the development of a product line and product members. In the case of third-party components, the documentation makes it possible to share and reuse the knowledge outside the organisation as well.

The interest of industry has focused on the technologies and methods used to develop better software architectures and on the technologies of software components. The importance of component documentation was noted in spring of 2000 in a practice survey, which examined the development needs of component software [21]. The component documentation was seen as one of the bottlenecks in the component development, acquirement and utilisation processes. The specified form in describing component capabilities was defined as being a prerequisite for component trading [21].

From the integrator's point of view, component documentation should provide information that will assist in the

  • selection of components,

  • validation of interoperability of components,

  • analysis of combined quality attributes, and

  • maintenance of components.

The scope of impact of a selected component is larger in product line based development than in the development of a single product. Therefore, much more effort has to be put into the selection and validation of a component. Special attention should also be paid to the analysis of combined quality attributes and maintenance of components, because the qualitative properties are often difficult to find out and the incompleteness of components may cause additional cost for integrators.

Nowadays, third-party components are not documented in a standard way, and therefore the software integrators have difficulties in finding out the capabilities of components. The lack of a standard documentation model has led to the fact that every component provider documents his components according to his own documentation guidelines. The consequences are that the documents are inconsistent, insufficient, and of varying quality, and the essential information may be missing or difficult to find.

A standard model is required to provide clear guidelines on how to document the properties of a component and to guarantee the consistency and quality of component documents. The model should also be applicable when, in the case of OCM components, the development of the component is split between organisations, because the delivered component meets the functional and quality requirements of a product line only if the integrator and the provider co-operate and follow a standard procedure to document it. The structure of component documentation should be organised in a logical way with which all necessary information is easy to determine.

Our contribution is a standard documentation pattern for software components. With a pattern we mean a model that can be repeatedly reused and applied to different occasions, and that is independent of the methods of implementation. The pattern defines all the required information that the component documentation must include, and also the logical structure of the documentation. The pattern has a product line based viewpoint on component documentation, i.e. it has been developed while examining how third-party components are developed and used in the context of product lines. The development of the documentation is defined by identifying the roles responsible for the development of a component and then associating them with the information that they produce for the component.

In Section 2 we introduce some previous documentation models and present the rationale for our documentation pattern in more detail. In Section 3 we introduce our pattern for component documentation. Section 4 presents the experimental trial and analyses of the pattern. After that we summarise our experiences and draw conclusions emphasising the most important research items of software component documentation.

Section snippets

Documentation approaches

Traditionally, components are documented as a part of the software systems in which they are involved [9], [24], [29]. Software documentation has usually been classified under two categories: process documentation and product documentation [29]. Process documentation concentrates on describing the software development process, including plans, reports, organisational standards and project standards. Product documentation can be divided into system documentation and user documentation. System

Component documentation pattern

The pattern (Fig. 3 and Appendix A) for documenting software components includes information produced by the different stakeholders involved in component development. COTS and OS components are documented by the component provider only. In the case of OCM components, the documentation is developed in collaboration between a component buyer (specified requirements) and a component developer (the rest of the document).

The product line architect defines the functional requirements and constraints

Lessons learned

In order to check the applicability of the documentation pattern, we carried out an experiment and two analyses. The experiment included the validation of the pattern by applying it in documentation of new components. The analyses consisted of pattern comparison with practice and pattern evaluation by industrial software engineers.

Conclusions

Proper documentation is required to verify the capabilities of a third-party component and assess its applicability to an architecture. That is the rationale for using a pattern for component documentation. The developed documentation pattern defines the information content and the structure of the documentation. The pattern is divided into four logically separate parts. The basic information describes the component's general properties and responsibilities from the architectural point of view.

References (35)

  • American Nuclear Society, American National Standard for Documentation of Computer Software, ANSI/ANS-10-3-1995,...
  • L Bass et al.

    Software Architecture in Practice

    (1998)
  • J Bosch

    Design and Use of Software Architectures. Adopting and Evolving a Product Line Approach

    (2000)
  • P Clements et al.

    Software Product Lines, Practices and Patterns

    (2001)
  • ESA, Guide to the user requirements definition phase, ESA Board for Software Standardisation and Control (BSSC), ESA...
  • M Forsell et al.

    A model for documenting reusable software components

  • G.T Heineman et al.

    Component-Based Software Engineering. Putting the Pieces Together

    (2001)
  • A. van Hoff, H. Partovi, T. Thai, The Open Software Description Format (OSD), Acknowledged Submissions to W3C, 1997....
  • Guidelines for the Documentation of Software in Industrial Computer Systems

    (1985)
  • IEEE Standard for Software User Documentation. IEEE Std 1063-1987

    (1988)
  • IEEE Standard Glossary of Software Engineering Terminology. IEEE Std 610.12-1990

    (1990)
  • IEEE Guide to Software Design Descriptions. IEEE Std 1016.1-1993

    (1993)
  • IEEE Standard for Software Test Documentation. IEEE Std 829-1998

    (1998)
  • IEEE Standard for Software Quality Assurance Plans. IEEE Std 730-2002

    (2002)
  • L Iribarne et al.

    Trading for COTS components in open environments

    Proceedings of the 27th Euromicro Conference on Component-Based Software Engineering, Warsaw, Poland, September 2001

    (2001)
  • ISO/IEC-9126, Information technology—Software product evaluation—Quality characteristics and guidelines for their use,...
  • P. Kallio, E. Niemelä, Documented Quality of COTS and OCM components, Fourth ICSE Workshop on Component-Based Software...
  • Cited by (22)

    • Cost, benefits and quality of software development documentation: A systematic mapping

      2015, Journal of Systems and Software
      Citation Excerpt :

      Based on the results of the joint voting, the size of the pool of selected papers decreased from 120 to 51. The excluded papers are Alan and Roger (1983), Alberto et al. (2005), Ambler (2002), Ashley (2004), Azmi and Ibrahim (2011), Bauer and Parnas (1995), Benson and Tom (1988), Berglund (2000), Berglund and Priestley (2001), Bethke et al. (1991), Bill et al. (1988), Thomas and Tilley (2001), Clark et al. (1989), Clear (2003), Clements et al. (2003), Courtois and Parnas (1993), Parnas et al. (1988), Parnas (2005), Delanghe (2000), Forward and Lethbridge (2014), French et al. (1997), Galdo et al. (1986), Gerth et al. (2014), Guillemette (1986), Haneef (1998), Hargis (2000), Hargis et al. (2004), Horowitz and Williamson (1985), Hyland-Wood et al. (2008), Jazzar and Scacchi (1995), Johnson and Rey (1994), Kalus and Torsten (1996), Landes et al. (1999), Landis et al. (1988), Liu (2001), Lobato et al. (2010), Luqi et al. (2003), Lutsky et al. (2000), Magyar (2000), Marcus and Maletic (2005), Marovac (1994), Marovac (1998), Medina (1984), Van der Meij (2000), Metzger et al. (2007), Moallem (2003), MacKinnon and Murphy (2004), Odenthal and Quibeldey-Cirkel (1997), Peters and Parnas (1998), Phoha (1997), Powell et al. (1996), Price (1984), Price and Korman (1993), Rob (2003), de Rosis et al. (1999), Ruth (1997), Sabou (2004), Tilley (1993), Tang et al. (2011), Taulavuori et al. (2004), Visconti and Cook (2002), Walters and Beck (1992), Wang et al. (2009), Wingkvist et al. (2010b), Wise (1993), Briand (2003) To minimize the risk of missing relevant papers, similar to previous SM papers and SLRs, we included additional papers manually via:

    • Using logical architecture models for inter-team management of distributed agile teams

      2022, International Journal of Information Technologies and Systems Approach
    View all citing articles on Scopus
    View full text