How organisation of architecture documentation affects architectural knowledge retrieval

• We compare retrieval from file-based and ontology-based architecture documentation.
• We investigate how the organisation of knowledge affects knowledge retrieval.
• Better knowledge organisation improves retrieval efficiency and effectiveness.
• We also report a cost–benefit analysis and survey on both documentation approaches.

A common approach to software architecture documentation in industry projects is the use of file-based documents. This approach offers a single-dimensional arrangement of the architectural knowledge. Knowledge retrieval from file-based architecture documentation is efficient if the organisation of knowledge supports the needs of the readers; otherwise it can be difficult. In this paper, we compare the organisation and retrieval of architectural knowledge in a file-based documentation approach and an ontology-based documentation approach. The ontology-based approach offers a multi-dimensional organisation of architectural knowledge by means of a software ontology and semantic wiki, whereas file-based documentation typically uses hierarchical organisation by directory structure and table of content. We conducted case studies in two companies to study the efficiency and effectiveness of retrieving architectural knowledge from the different organisations of knowledge. We found that the use of better knowledge organisation correlates with the efficiency and effectiveness of AK retrieval. Professionals who used the knowledge organisation found this beneficial.