# A Study of Documentation for Software Architecture

**Authors:** Neil A. Ernst, Martin P. Robillard  
**arXiv:** [2305.17286](https://arxiv.org/abs/2305.17286)  
**Date:** 2023-05-26  
**Summary page:** https://www.summarizepaper.com/en/paper/2305.17286v1/

## Key points

- The impact of different formats of architectural documentation on newcomers' understanding of software projects was investigated in the study.
- 65 participants were asked to answer software architecture questions using either narrative essays or structured documents.
- Results showed that the format of the documentation did not significantly affect participants' performance in understanding the architecture.
- Prior exposure to the source code emerged as a key factor associated with answer quality.
- Potential biases such as observer-expectancy effect and non-participation rates were considered but had minimal impact on study results.
- Acknowledged limitations in document length and task complexity, noting findings may not directly apply to longer onboarding processes or more complex architectural documents.
- Study provided valuable insights into effective use of software architecture documentation, emphasizing prior familiarity with source code and types of architectural information sought as crucial factors influencing newcomers' understanding.

## Summary

The impact of different formats of architectural documentation on newcomers' understanding of software projects was investigated in this study. 65 participants were asked to answer software architecture questions using either narrative essays or structured documents. Surprisingly, the results showed that the format of the documentation did not significantly affect the participants' performance in understanding the architecture. Instead, prior exposure to the source code emerged as a key factor associated with answer quality. The researchers also considered potential biases such as observer-expectancy effect and non-participation rates but concluded that these factors had minimal impact on the study results. They acknowledged limitations in terms of document length and task complexity and noted that their findings may not directly apply to longer onboarding processes or more complex architectural documents. Despite these limitations, the study provided valuable insights into effective use of software architecture documentation. It highlighted the importance of prior familiarity with source code and identified types of architectural information sought as crucial factors influencing newcomers' understanding. Overall, while acknowledging the controlled nature of their study, the researchers emphasized that their results contribute to a better understanding of how different factors influence newcomers' comprehension of software architecture documentation.