A study of the documentation essential to software maintenance

Software engineering has been striving for years to improve the practice of software development and maintenance. Documentation has long been prominent on the list of recommended practices to improve development and help maintenance. Recently however, agile methods started to shake this view, arguing that the goal of the game is to produce software and that documentation is only useful as long as it helps to reach this goal.On the other hand, in the re-engineering field, people wish they could re-document useful legacy software so that they may continue maintain them or migrate them to new platform.In these two case, a crucial question arises: "How much documentation is enough?" In this article, we present the results of a survey of software maintainers to try to establish what documentation artifacts are the most useful to them.

[1]  Grace A. Lewis,et al.  Modernizing Legacy Systems - Software Technologies, Engineering Processes, and Business Practices , 2003, SEI series in software engineering.

[2]  Meir M. Lehman.  Programs, life cycles, and laws of software evolution , 1980 .

[3]  Vir V. Phoha.  A Standard for Software Documentation , 1997, Computer.

[4]  Lionel C. Briand,et al.  Software documentation: how much is enough? , 2003, Seventh European Conference onSoftware Maintenance and Reengineering, 2003. Proceedings..

[5]  Thomas M. Pigoski.  Practical Software Maintenance: Best Practices for Managing Your Software Investment , 1996 .

[6]  Timothy Lethbridge,et al.  The relevance of software documentation, tools and technologies: a survey , 2002, DocEng '02.

[7]  Kent L. Beck.  Extreme Programming , 1999, TOOLS.

[8]  Shihong Huang,et al.  Towards a documentation maturity model , 2003, SIGDOC '03.

[9]  Mira Kajko-Mattsson,et al.  The state of documentation practice within corrective maintenance , 2001, Proceedings IEEE International Conference on Software Maintenance. ICSM 2001.

[10]  Barry W. Boehm,et al.  Empirical Findings in Agile Methods , 2002, XP/Agile Universe.

[11]  Václav Rajlich,et al.  Incremental Redocumentation Using the Web , 2000, IEEE Software.

[12]  Roger S. Pressman,et al.  Software Engineering: A Practitioner's Approach (McGraw-Hill Series in Computer Science) , 2004 .

[13]  Penny Grubb,et al.  Software Maintenance: Concepts and Practice , 2003 .

[14]  Scott R. Tilley,et al.  Documenting-in-the-large vs. documenting-in-the-small , 1993, CASCON.

[15]  Hausi A. Müller,et al.  Documenting software systems with views , 1992, SIGDOC '92.

[16]  M.M. Lehman,et al.  Programs, life cycles, and laws of software evolution , 1980, Proceedings of the IEEE.

[17]  Roger S. Pressman,et al.  Software Engineering: A Practitioner's Approach , 1982 .

[18]  Tim Murphy,et al.  Extreme maintenance , 2001, Proceedings IEEE International Conference on Software Maintenance. ICSM 2001.

[19]  Frank A. Cioch,et al.  A documentation suite for maintenance programmers , 1996, 1996 Proceedings of International Conference on Software Maintenance.

[20]  Scott R. Tilley,et al.  Documentation for software engineers: what is needed to aid system understanding? , 2001, SIGDOC '01.

[21]  Janice Singer,et al.  Towards an ontology of software maintenance , 1999, J. Softw. Maintenance Res. Pract..

[22]  Rodolfo Alfredo Bertone,et al.  Software engineering: Theory and practice, 2nd Edition. Shari Lawrence Pfleeger. Prentice Hall, 2001 , 2005 .

[23]  Will Venters,et al.  Software engineering: theory and practice , 2006 .

[24]  Nicolas Anquetil,et al.  Software Re-Documentation Process and Tool , 2005, CAiSE Short Paper Proceedings.

[25]  Maria Joao C. Sousa,et al.  A survey on the Software Maintenance Process , 1998, Proceedings. International Conference on Software Maintenance (Cat. No. 98CB36272).

[26]  Hausi A. Müller,et al.  INFO: a simple document annotation facility , 1991, SIGDOC '91.