Experimental Analysis of Textual and Graphical Representations for Software Architecture Design

Software architecture design documentation should communicate design decisions effectively. However, little is known about the way recipients respond to the different types of media used in documentation. We therefore conducted a controlled experiment to study whether visual or textual artifacts are more effective in communicating architecture software design decisions to software developers. Our participant group consisted of 47 participants from both industry and academia. Our results show that neither diagrams nor textual descriptions proved to be significantly more efficient in terms of communicating software architecture design decisions. Remarkably, participants who predominantly used text, scored significantly better, overall and with respect to topology related questions. Furthermore, surprisingly, diagrams were not able to alleviate the difficulties participants with a native language other than English had in extracting information from the documentation. In combination, these findings at the very least question the role of diagrams in software architecture documentation.