Skip to main content
U.S. flag

An official website of the United States government

Official websites use .gov
A .gov website belongs to an official government organization in the United States.

Secure .gov websites use HTTPS
A lock ( ) or https:// means you’ve safely connected to the .gov website. Share sensitive information only on official, secure websites.

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

Published

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

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 July 14, 2024)

Issues

If you have any questions about this publication or are having problems accessing it, please contact reflib@nist.gov.

Created May 1, 2001, Updated February 17, 2017