Skip to main content
SpringerLink
Log in

Producing Just Enough Documentation: An Optimization Approach Applied to the Software Architecture Domain

  • Original Article
  • Area 3
  • Published:
Journal on Data Semantics

Abstract

The Software Architecture is an important asset in a software development process, which serves to share and discuss the main design concerns among the project stakeholders. The architecture must be properly documented (e.g., via a Wiki environment) to be effectively used by these stakeholders. However, the process of producing architecture documentation often fails to deliver contents that address the stakeholders’ information needs. To address the problem, we argue for a knowledge management strategy in which: (i) architecture documentation is created incrementally; and (ii) its contents are driven by a model of stakeholder preferences. In this work, we present an information optimization approach applied to the architecture documentation domain, derived from an existing documentation method called Views & Beyond. To do so, we define the Next SAD Version Problem (NSVP) and then provide tool support to assist architects in producing cost-effective documentation. Based on prior work, we perform a sensitivity analysis of the optimization model and develop a robust formulation that takes into account uncertainty in the parameter estimations for NSVP instances, thus improving the outcomes of our documentation assistant.

This is a preview of subscription content, log in via an institution to check access.

Access this article

Log in via an institution

Price excludes VAT (USA)
Tax calculation will be finalised during checkout.

Instant access to the full article PDF.

Institutional subscriptions

Fig. 1
Fig. 2
Fig. 3
Fig. 4
Fig. 5
Fig. 6
Fig. 7
Fig. 8
Fig. 9
Fig. 10
Fig. 11

Similar content being viewed by others

Notes

  1. This role is usually played by members of the architecture team.

  2. http://moeaframework.org/

  3. https://waterprogramming.wordpress.com/2012/08/13/running-sobol-sensitivity-analysis-using-moeaframework/.

  4. http://people.cs.clemson.edu/johnmc/courses/cpsc875/resources/Telematics

    Fig. 7
    figure 7

    Steps of the Sobol sensitivity analysis applied to NSVP_BD

    Full size image
    Fig. 8
    figure 8

    Sobol sensitivity indices computed for the CTAS SAD

    Full size image

  5. OpenNLP homepage: http://opennlp.apache.org/.

  6. Porter’s Stemming homepage: http://snowball.tartarus.org/.

References

  1. Al Halabi WS, Kubat M, Tapia M (2007) Time spent on a web page is sufficient to infer a user’s interest. In: IASTED European Conference on Proceedings of the IASTED European Conference: internet and multimedia systems and applications. ACTA Press, Anaheim, CA, USA, pp 41–46

  2. Bachmann F, Merson P (2005) Experience using the web-based tool wiki for architecture documentation. Technical Note CMU/SEI-2005-TN-041, SEI, Carnegie Mellon University, Pittsburgh, Pennsylvania

  3. Baeza-Yates R, Ribeiro-Neto B (2011) Modern information retrieval: the concepts and technology behind search, 2nd edn. Addison-Wesley Professional

  4. Bass L, Kazman R, Ozkaya I (2011) Developing architectural documentation for the hadoop distributed file system. In: Hissam S, Russo B, de Mendonca Neto M, Kon F (eds) Open Source Systems: Grounding Research, IFIP Advances in Information and Communication Technology, vol 365, Springer Boston, pp 50–61

  5. Bass L, Clements P, Kazman R (2012) Software Architecture in Practice, 3rd edn. Addison-Wesley Professional

  6. Berre DL, Parrain A (2010) The sat4j library. release 2.2. JSAT 7(2–3):59–6

  7. Bertsimas D, Sim M (2004) The price of robustness. Oper Res 52(1):35–53

    Article  MathSciNet  MATH  Google Scholar 

  8. Beyer HG, Sendhoff B (2007) Robust optimization—a comprehensive survey. Comput Methods Appl Mech Eng 196(33–34):3190–3218

    Article  MathSciNet  MATH  Google Scholar 

  9. de Boer RC, van Vliet H (2008) Architectural knowledge discovery with latent semantic analysis: constructing a reading guide for software product audits. J Syst Softw 81(9):1456–1469

    Article  Google Scholar 

  10. Cannataro M, Cuzzocrea A, Mastroianni C, Ortale R, Pugliese A, università Della Calabria D (2002) Modeling adaptive hypermedia with an object-oriented approach and xml. In: In Proc. of WebDyn’02

  11. Castro-Herrera C, Cleland-Huang J, Mobasher B (2009) Enhancing stakeholder profiles to improve recommendations in online requirements elicitation. In: Requirements Engineering Conference, 2009. RE ’09. 17th IEEE International, pp 37–46

  12. Claypool M, Le P, Wased M, Brown D (2001) Implicit interest indicators. In: Proceedings of the 6th international conference on Intelligent user interfaces, ACM, New York, NY, USA, IUI ’01, pp 33–40

  13. Clements P, Bachmann F, Bass L, Garlan D, Ivers J, Little R, Nord R, Stafford J (2003) A practical method for documenting software architectures. In: ICSE

  14. Clements P, Bachmann F, Bass L, Garlan D, Ivers J, Little R, Merson P, Nord R, Stafford J (2010) Documenting software architectures: views and beyond, 2nd edn. Addison-Wesley Professional

  15. Cuzzocrea A (2006) Combining multidimensional user models and knowledge representation and management techniques for making web services knowledge-aware. Web Intell Agent Sys 4(3):289–312

    Google Scholar 

  16. Deb K, Pratap A, Agarwal S, Meyarivan T (2002) A fast and elitist multiobjective genetic algorithm: Nsga-ii. Trans Evol Comp 6(2):182–197

    Article  Google Scholar 

  17. Diaz-Pace JA, Nicoletti M, Schiaffino S, Vidal S (2014) Producing just enough documentation: The next sad version problem. In: Le Goues C, Yoo S (eds) Search-Based Software Engineering, Lecture Notes in Computer Science, vol 8636, Springer International Publishing, pp 46–60

  18. Diwekar U (2010) Introduction to applied optimization, 2nd edn. Springer Publishing Company, Incorporated

  19. Falessi D, Briand LC, Cantone G, Capilla R, Kruchten P (2013) The value of design rationale information. ACM Trans Softw Eng Methodol 22(3):21

    Article  Google Scholar 

  20. Farenhorst R, Lago P, van Vliet H (2007) Eagle: effective tool support for sharing architectural knowledge. Int J Coop Inf Syst 16(3/4):413–437

    Article  Google Scholar 

  21. Farenhorst R, Izaks R, Lago P, Vliet Hv (2008) A just-in-time architectural knowledge sharing portal. In: Proceedings Working IEEE/IFIP Conference on Software Architecture (WICSA 2008), IEEE Computer Society, Washington, DC, USA, WICSA ’08, pp 125–134

  22. de Graaf KA, Tang A, Liang P, van Vliet H (2012) Ontology-based software architecture documentation. In: Proceedings Joint Working Conf. on Software Architecture & European Conf. on Software Architecture (WICSA/ECSA), IEEE Computer Society, WICSA 2012, pp 315–319

  23. Hadar I, Sherman S, Hadar E, Harrison J (2013) Less is more: Architecture documentation for agile development. In: Cooperative and Human Aspects of Software Engineering (CHASE), 2013 6th International Workshop on, pp 121–124

  24. Hofmeister C, Nord R, Soni D (2000) Applied Software Architecture, 1st edn. Addison-Wesley Professional

  25. Hoorn JF, Farenhorst R, Lago P, van Vliet H (2011) The lonesome architect. J Syst Softw 84(9):1424–1435

    Article  Google Scholar 

  26. IEEE (2000) Ieee std 1471-2000: Recommended practice for architectural description of software-intensive systems

  27. ISO/IEC/IEEE (2011) Iso/iec/ieee 42010: Systems and software engineering—architecture description

  28. Jansen A, Bosch J (2005) Software architecture as a set of architectural design decisions. In: Proceedings Working Conf. on Software Architecture, IEEE Computer Society, pp 109–120

  29. Jansen A, Avgeriou P, van der Ven JS (2009) Enriching software architecture documentation. J Syst Softw 82(8):1232–1248

    Article  Google Scholar 

  30. Keuler T, Knodel J, Naab M, Rost D (2012) Architecture engagement purposes: Towards a framework for planning ’just enough’-architecting in software engineering. In: Software Architecture (WICSA) and European Conference on Software Architecture (ECSA), 2012 Joint Working IEEE/IFIP Conference on, pp 234–238

  31. Koning H, Vliet HV (2006) Real-life it architecture design reports and their relation to ieee std 1471 stakeholders and concerns. Autom Softw Eng 13:201–223

    Article  Google Scholar 

  32. Kruchten P (1995) The 4+1 view model of architecture. IEEE Softw 12(6):42–50

    Article  Google Scholar 

  33. Lattanze A (2008) Architecting software intensive systems: a practitioners guide. Taylor & Francis

  34. Mitchell RK, Agle BR, Wood DJ (1997) Toward a theory of stakeholder identification and salience: defining the principle of who and what really counts. Acad Manag Rev 22:853

    Google Scholar 

  35. Naeem S, Imtiaz S (2014) Architecture coverage: Validating optimum set of viewpoints. In: Proceedings of the 9th International Conference on Software Engineering Advances (ICSEA)

  36. Nicoletti M, Diaz-Pace JA, Schiaffino S (2012) Towards software architecture documents matching stakeholders interests. In: Cipolla-Ficarra F (ed) Advances in New Technologies, Interactive Interfaces and Communicability, no. 7547 in LNCS, Springer Berlin Heidelberg, pp 176–185

  37. Nicoletti M, Diaz-Pace J, Schiaffino S, Tommasel A, Godoy D (2014) Personalized architectural documentation based on stakeholders information needs. J Softw Eng Res Dev 2(1):9

    Google Scholar 

  38. Pace JAD, Nicoletti M, Schiaffino SN, Villavicencio C, Sanchez LE (2013) A stakeholder-centric optimization strategy for architectural documentation. In: Model and Data Engineering—Third International Conference, MEDI 2013, Amantea, Italy, September 25-27, 2013. Proceedings, pp 104–117

  39. Paixão M, Souza J (2013) A scenario-based robust model for the next release problem. In: Proceedings of the 15th Annual Conference on Genetic and Evolutionary Computation, ACM, New York, NY, USA, GECCO ’13, pp 1469–1476

  40. Parnas DL (2010) Precise documentation: The key to better software. In: Nanz S (ed) The Future of Software Engineering, Springer, pp 125–148

  41. Rost D, Naab M, Lima C, von Chavez CFG (2013) Software architecture documentation for developers: a survey. In: Proceedings of 7th ECSA, Springer-Verlag, Berlin, Heidelberg, pp 72–88

  42. Rozanski N, Woods E (2011) Software Systems Architecture: Working With Stakeholders Using Viewpoints and Perspectives, 2nd edn. Addison-Wesley

  43. Saltelli A, Tarantola S, Campolongo F, Ratto M (2004) Sensitivity analysis in practice: a guide to assessing scientific models. Halsted Press, New York

    Google Scholar 

  44. Savolainen J, Mannisto T (2010) Conflict-centric software architectural views: exposing trade-offs in quality requirements. IEEE Softw 27(6):33–37

    Article  Google Scholar 

  45. Schiaffino S, Amandi A (2009) Intelligent user profiling. In: Bramer M (ed) Artificial Intelligence: An International Perspective, Lecture Notes in Computer Science, vol 5640, Springer Berlin/Heidelberg, pp 193–216

  46. Sobol IM (2001) Global sensitivity indices for nonlinear mathematical models and their monte carlo estimates. Math Comput Simul 55(1–3):271–280

    Article  MathSciNet  MATH  Google Scholar 

  47. Su MT (2010) Capturing exploration to improve software architecture documentation. In: Proceedings 4th European Conference on Software Architecture: Companion Volume, ACM, New York, NY, USA, ECSA ’10, pp 17–21

  48. Su MT, Hosking J, Grundy J (2011) Capturing architecture documentation navigation trails for content chunking and sharing. In: 2011 9th Working IEEE/IFIP Conference on Software Architecture (WICSA), pp 256–259

  49. Unphon H, Dittrich Y (2010) Software architecture awareness in long-term software product evolution. J Syst Softw 83(11):2211–2226

    Article  Google Scholar 

  50. Yu G (1996) On the max-min 0–1 knapsack problem with robust optimization applications. Oper Res 44(2):407–415

    Article  MathSciNet  MATH  Google Scholar 

Download references

Acknowledgments

This work was partially supported by ANPCyT (Argentina) through PICT Project 2011 No. 0366, and also by CONICET (Argentina) through PIP Project No. 112-201101-00078.

Author information

Authors and Affiliations

  1. ISISTAN Research Institute, CONICET-UNICEN, Campus Universitario, Paraje Arroyo Seco (B7001BBO), Tandil, Argentina

    J. Andrés Díaz-Pace, Christian Villavicencio, Silvia Schiaffino, Matías Nicoletti & Hernán Vázquez

Authors
  1. J. Andrés Díaz-Pace
    View author publications

    You can also search for this author in PubMed Google Scholar

  2. Christian Villavicencio
    View author publications

    You can also search for this author in PubMed Google Scholar

  3. Silvia Schiaffino
    View author publications

    You can also search for this author in PubMed Google Scholar

  4. Matías Nicoletti
    View author publications

    You can also search for this author in PubMed Google Scholar

  5. Hernán Vázquez
    View author publications

    You can also search for this author in PubMed Google Scholar

Corresponding author

Correspondence to J. Andrés Díaz-Pace.

Rights and permissions

Reprints and permissions

About this article

Check for updates. Verify currency and authenticity via CrossMark

Cite this article

Díaz-Pace, J.A., Villavicencio, C., Schiaffino, S. et al. Producing Just Enough Documentation: An Optimization Approach Applied to the Software Architecture Domain. J Data Semant 5, 37–53 (2016). https://doi.org/10.1007/s13740-015-0053-0

Download citation

  • Received:

  • Accepted:

  • Published:

  • Issue Date:

  • DOI: https://doi.org/10.1007/s13740-015-0053-0

Keywords

Search

Navigation