Architecture documentation for developers: A survey

Software architecture has become an established discipline in industry and documentation is the key for its efficient and effective usage. However, many companies do not have any architecture documentation in place or, if they do, the available documentation is not perceived as adequate by developers to support them in their tasks. To complement our experiences from projects with industry customers and as a foundation for the improvement of methods and tools in architecture documentation, we conducted a survey among 147 industrial participants, investigating their current problems and wishes for the future. Participants from different countries in Europe, Asia, North and South America shared their experiences. This report presents the results of the survey. We identified five main findings. The results confirm the common belief that architecture documentation is most frequently outdated, updated only with strong delays, and inconsistent in detail and form and backed it up with data. Further, developers perceive difficulties with a "one-size-fits-all" architecture documentation, which does not adequately provide information for their specific tasks and contexts. Developers seek more interactive ways of working with architecture documentation that allow them to find needed information more easily with extended navigation and search possibilities. And finally, what developers perceive as relevant in terms of architecture information gives, in our opinion, a very complete and mature picture of what software architecture and its documentation should consist of. Based on these results, we discuss directions for further research and the development of advanced methods and tools for architecture documentation in this report. Centralization with powerful tooling and automated generation mechanisms are possible means for addressing the problems of outdated and unspecific architecture documentation. Additionally, a clear, easy-to-follow connection between architecture an code is a major concern of developers for which new techniques have to be created. To achieve increased uniformity, organizations should invest in internal standardization in terms of form, details, and terminology, as well as in establishing a single source of architecture documentation to avoid inefficiency due to scattered information. We understand that static architecture documents must be replaced by new and interactive ways to convey the information that allow easy searching and navigation. And finally, to increase readability and understandability, we see an additional need for standardization and clarity through reduction of information