Characteristics of ADLs That Support Good Architecture Documentation: A Position Paper for the SEI Software

Published

May 1, 2001

Author(s)

Christopher E. Dabrowski

Abstract

One of the potential benefits of describing software architecture is the ability to provide greater clarity and understanding than what is possible in program code. The concise representation of the essential aspects of the functional components of a system, their connections and interactions, and their behavior provides a basis for communicating system design. This serves as documentation for different stakeholders and participants in the system design process, including system analysts, designers, implementers, maintainers, and managers.In current software practice, the development of comprehensive documentation of any aspect of a system--including its architecture--is often lengthy and tedious. This is particularly the case when describing a system using a terminology familiar to customers or when it is necessary to provide alternative views of a system to different stakeholders. To provide the greatest benefit with the least amount of effort, it should be possible for an architecture description to be stated completely in a specification created using the ADL. That is, a specification written in an ADL should be as self-documenting as possible. While additional text will always be required to provide context and design rational, the actual specification of software architecture in the ADL should be definitive enough not to require large amounts of additional explanation and comments. This position paper makes recommendations on good characteristics of architecture documentation and discusses ADL features that support such characteristics.

Proceedings Title

Proceedings of Software Engineering Documentation Workshop

Conference Dates

January 16-17, 2001

Conference Title

Software Engineering Documentation Workshop

Pub Type

Conferences

Keywords

architectural description language, architectural view, architecture documentation, software architecture, software documentation

Citation

Dabrowski, C. (2001), Characteristics of ADLs That Support Good Architecture Documentation: A Position Paper for the SEI Software, Proceedings of Software Engineering Documentation Workshop (Accessed February 14, 2025)