An Explanation of Software Architecture Explanations

Software architecture knowledge transfer is essential for software development, but related documentation is often incomplete or ambiguous, making oral explanations a common means. Our broader aim is to explore how such explanations might be better supported and eventually automated; as a prerequisite, we first investigate how explanations are actually conducted in practice across five areas: explanation topics, explanation plans, supporting artefacts, typical questions, and expectations and challenges. We report on semi-structured interviews with 17 software professionals across diverse organisations and countries. Our findings include that explanations must balance problem- and technical-domain while considering the explainee's role, experience, and goals. Moreover, explainees frequently seek not only structure and behaviour, but also decision rationale. We propose the Explanation Window, a framework for focusing information by adjusting functionality scope and detail, and emphasise the importance of including system context. These findings provide an empirical basis for improving architecture explanations and guiding future work on tool support and automation.