Abstract:Documentation is an important mechanism for disseminating software architecture knowledge. Software project teams can employ vastly different formats for documenting software architecture, from unstructured narratives to standardized documents. We explored to what extent this documentation format may matter to newcomers joining a software project and attempting to understand its architecture. We conducted a controlled questionnaire-based study wherein we asked 65 participants to answer software architecture understanding questions using one of two randomly-assigned documentation formats: narrative essays, and structured documents. We analyzed the factors associated with answer quality using a Bayesian ordered categorical regression and observed no significant association between the format of architecture documentation and performance on architecture understanding tasks. Instead, prior exposure to the source code of the system was the dominant factor associated with answer quality. We also observed that answers to questions that require applying and creating activities were statistically significantly associated with the use of the system's source code to answer the question, whereas the document format or level of familiarity with the system were not. Subjective sentiment about the documentation format was comparable: Although more participants agreed that the structured document was easier to navigate and use for writing code, this relation was not statistically significant. We conclude that, in the limited experimental context studied, our results contradict the hypothesis that the format of architectural documentation matters. We surface two more important factors related to effective use of software architecture documentation: prior familiarity with the source code, and the type of architectural information sought.

System-of-Systems Viewpoint for System Architecture Documentation

Using information activity and capability effect to bridge gaps between OV, CV and SV/SvcV

System of systems - An overview

Ontology-Based Architecture Process of System-of-Systems: from Capability Development to Operational Modeling

Overview of Expert Systems Based on SOA

System of Systems-an Overview

Documentation-Based Approach to Reveal Architectural View Conflicts

System-of-Systems Engineering Management: A Review of Modern History and a Path Forward

Application of Executive Views for System-of-Systems Decision Making in the U.S.Army

System of systems software architecture description using the ISO/IEC/IEEE 42010 standard

Principled and automated system of systems composition using an ontological architecture

A methodology for developing SoS architectures using SysML model federation

System of Systems Architecture Prioritization Using A Comprehensive Evaluation Framework

Inconsistency Handling of Viewpoints: An Epistemic Logic-Based Approach

Software Architecture Documentation: the Road Ahead.

Executable Architecture Modeling and Analysis for System-of-systems

A Study of Documentation for Software Architecture

Evaluation Method of System-of-systems Architecture Using Knowledge-Based Executable Model

Functionality Evaluation of System of Systems Architecture Based on Extended Influence Diagrams

SoS applications in production/manufacturing domain: a review and discussion

Sos Architecture Alternatives Tradespace Modeling and Computable Experimentation: A Framework with System Engineering Thinking