Task-Specific Architecture Documentation for Developers

Why Separation of Concerns in Architecture Documentation is Counterproductive for Developers
Conference paper
Part of the Lecture Notes in Computer Science book series (LNCS, volume 9839)


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.


Architecture documentation Architecture knowledge Architecture realization Developers Implementation Task Separation of concerns 


  1. 1.
    Fairbanks: Just Enough Software Architecture: A Risk-Driven Approach. Marshall & Brainerd (2010)Google Scholar
  2. 2.
    Perry, D.E., Wolf, A.L.: Foundations for the study of software architecture. ACM SIGSOFT Softw. Eng. Notes 17, 40–52 (1992)CrossRefGoogle Scholar
  3. 3.
    Clements, P., Bachmann, F., Bass, L., Garlan, D., Ivers, J., Little, R., Merson, P., Nord, R., Stafford, J.: Documenting Software Architectures: Views and Beyond. Addison-Wesley Professional, Boston (2002)Google Scholar
  4. 4.
    Hofmeister, C., Nord, R., Soni, D.: Applied Software Architecture. Addison-Wesley Professional, Boston (1999)Google Scholar
  5. 5.
    Bayer, J., Muthig, D.: A view-based approach for improving software documentation practices. In: 13th Annual IEEE International Symposium and Workshop on Engineering of Computer-Based Systems, ECBS 2006, pp. 269–278 (10 p.) (2006)Google Scholar
  6. 6.
    Capilla, R., Jansen, A., Tang, A., Avgeriou, P., Babar, M.A.: 10 years of software architecture knowledge management: practice and future. J. Syst. Softw. 116, 191–205 (2015)CrossRefGoogle Scholar
  7. 7.
    Farenhorst, R., Lago, P., van Vliet, H.: EAGLE: effective tool support for sharing architectural knowledge. Int. J. Coop. Inf. Syst. 16, 413–437 (2007)CrossRefGoogle Scholar
  8. 8.
    Chen, L., Babar, M.A., Liang, H.: Model-centered customizable architectural design decisions management. In: 2010 21st Australian Software Engineering Conference, pp. 23–32. IEEE (2010)Google Scholar
  9. 9.
    Manteuffel, C., Tofan, D., Koziolek, H., Goldschmidt, T., Avgeriou, P.: Industrial implementation of a documentation framework for architectural decisions. In: 2014 IEEE/IFIP Conference on Software Architecture, pp. 225–234. IEEE (2014)Google Scholar
  10. 10.
    Rost, D.: Generation of task-specific architecture documentation for developers. In: Proceedings of the 17th International Doctoral Symposium on Components and Architecture - WCOP 2012, p. 1. ACM Press, New York (2012)Google Scholar
  11. 11.
    Rost, D., Naab, M., Lima, C., Flach Garcia Chavez, C.: Software architecture documentation for developers: a survey. In: Drira, K. (ed.) ECSA 2013. LNCS, vol. 7957, pp. 72–88. Springer, Heidelberg (2013). doi: 10.1007/978-3-642-39031-9_7 CrossRefGoogle Scholar
  12. 12.
    Naab, M., Braun, S., Lenhart, T., Hess, S., Eitel, A., Magin, D., Carbon, R., Kiefer, F.: Why data needs more attention in architecture design - experiences from prototyping a large-scale mobile app ecosystem. In: 2015 12th Working IEEE/IFIP Conference on Software Architecture, pp. 75–84. IEEE (2015)Google Scholar

Copyright information

© Springer International Publishing AG 2016

Authors and Affiliations

  1. 1.Fraunhofer IESEKaiserslauternGermany

Personalised recommendations