From Expert to Novice: An Empirical Study on Software Architecture Explanations

2025-03-11

AI Summary

Inefficient software architecture knowledge transfer during onboarding—due to incomplete documentation and ad hoc verbal explanations—hinders new developers’ understanding. Method: We conducted an empirical study via semi-structured interviews with 17 practitioners. Contribution/Results: We introduce the “explanation window” concept—a dynamic mechanism for adjusting technical depth and scope—and extend the Twin Peaks model to explicitly represent co-evolution among problem domain, solution domain, and contextual factors. Our findings reveal that effective architectural explanation requires bidirectional adaptation to the listener’s role, experience, and goals, while simultaneously addressing both problem and solution domains. Based on these insights, we derive five actionable improvement directions. This work establishes the first empirically grounded theoretical framework and practical guidelines for designing architecture knowledge transfer tools and optimizing onboarding processes.

Technology Category

• Cognitive Modeling & Cognitive Systems: Agent Architectures
• Knowledge Representation and Reasoning: Diagnosis and Abductive Reasoning
• Multiagent Systems: Agent/AI Theories and Architectures

Application Category

• User Modeling, Personalization and Recommendation: Explainable and interpretable methods for personalization
• Web Mining and Content Analysis: Models for Web evolution
• Semantics and Knowledge: Data modeling to support human-machine intelligence, including LLMs agents, intelligent system behavior, explanations, and user-friendly interactions

Abstract

The sharing of knowledge about software architecture is crucial in software development, particularly during the onboarding of new developers. However, existing documentation often falls short due to issues like incompleteness and ambiguity. Consequently, oral explanations are used for knowledge transfer. This study investigates what constitutes a good explanation of software architecture through an empirical study. It aims to explore how software architecture explanations are conducted, identify the main challenges, and suggest improvements. It addresses five key areas: relevant architectural concerns, explanation plans, supporting artefacts, typical questions, and expectations. An exploratory field study was conducted using semi-structured interviews with 17 software professionals, including 9 architecture explainers and 8 explainees. The study discovers that an explanation must balance both problem and technical domains while considering the explainee's role, experience, and the goal of the explanation. The concept of the explanation window, which adjusts the level of detail and scope, is introduced to address these variables. We also extend the Twin Peaks model to guide the interplay between problem and solution domains during architectural explanations by adding an emphasis to the context surrounding both domains. Future research should focus on developing better tools and processes to support architecture explanations.

Problem

• Improving software architecture knowledge transfer
• Identifying challenges in architectural explanations
• Enhancing tools for effective architecture communication

Innovation

• Exploration of software architecture explanation methods
• Introduction of the explanation window concept
• Extension of the Twin Peaks model