Documenting Agile Architecture: Practices and Recommendations

Abstract

Architecture is the foundation of every software product, regardless of the process used for its development. Traditional architecture development based on three architectural phases – architectural analysis, synthesis and evaluation is considered highly ceremonial, due to the great number of artifacts it produces. In agile development, architecture is generated gradually with each iteration, as a result of continuous code refactoring, not some predefined structure. In other words, agile processes do not include any of the traditional phases (analysis, synthesis, and evaluation) of the architecture development process, while self-documenting code is the predominant form agile architecture documentation.

Excessive documentation is considered wasteful in agile development processes. However, complete elimination of documentation results in “evaporation” of architectural information and knowledge, which may compromise the entire development process. Therefore, development of complex software systems requires an architecture documenting strategy positioned between the described extremes.

This paper presents results of theoretical and empirical research on documenting software architecture in agile development processes. Subsequent to the systematic literature review, an empirical research based on the classic Delphi method was carried out on a sample of 20 expert practitioners. In addition to an overview of current architecture documenting practices, the paper proposes structures of two artifacts for documenting agile architecture of complex systems, developed with regard to the results of the empirical research. These artifacts contain short descriptions of architectural decisions and rationale behind them.