Task-specific architecture documentation for developers: Why separation of concerns in architecture documentation is counterproductive for developers

Abstract

It is widely agreed that architecture documentation, independent of its form, is necessary to prescribe architectural concepts for development and to conserve architectural information over time. However, very often architecture documentation is perceived as inadequate, too long, too abstract, too detailed, or simply outdated. While developers have tasks to develop certain features or parts of a system, they are confronted with architecture documents that globally describe the architecture and use concepts like separation of concerns. Then, the developers have the hard task to find all information of the separated concerns and to synthesize the excerpt relevant for their concrete task. Ideally, they would get an architecture document, which is exactly tailored to their need of architectural information for their task at hand. Such documentation can however not be created by architects in reasonable time. In this paper, we propose an approach of modeling architecture and automatically synthesizing a tailored architecture documentation for each developer and each development task. Therefore architectural concepts are selected from the model based on the task and an interleaving of concepts is done. This makes for example all interfaces explicit, which a component has to implement in order to comply with security, availability, etc. concepts. The required modeling and automation is realized in the tool Enterprise Architect. We got already very positive feedback for this idea from practitioners and expect a significant improvement of implementation quality and architecture compliance.