A study of the documentation essential to software maintenance

ABSTRACT

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.

REFERENCES

• 1: V. M. aes Teles. Extreme Programming. Novatec Editora Ltda, Rua cons. Moreira de Barros, 1084, conj. 01, São Paulo, SP, 02018-012, Brazil, 2004. ISBN: 85-7522-047-0.
• 2: S. W. Ambler. Agile documentation. available on the internet at: http://www.agilemodeling.com/essays/agileDocumentation.htm, 2001-2005. Last accessed on May 27, 2005.
• 3: N. Anquetil, K. M. Oliveira, A. G. dos Santos, P. C. da Silva jr., L. C. de Araujo jr., and S. D. Vieira. A tool to automate re-documentation. In Forum of the CAISE, Conference on Advanced Information Systems Engineering (CAiSE'05), jun. 15 2005. accepted for publication.
• 4: Maria Joao Sousa, A Survey on the Software Maintenance Process, Proceedings of the International Conference on Software Maintenance, p.265, March 16-19, 1998
• 5: Lionel C. Briand, Software Documentation: How Much Is Enough?, Proceedings of the Seventh European Conference on Software Maintenance and Reengineering, p.13, March 26-28, 2003
• 6: Frank A. Cioch , Michael Palazzolo , Scott Lohrer, A Documentation Suite for Maintenance Programmers, Proceedings of the 1996 International Conference on Software Maintenance, p.286-295, November 04-08, 1996
• 7: Andrew Forward , Timothy C. Lethbridge, The relevance of software documentation, tools and technologies: a survey, Proceedings of the 2002 ACM symposium on Document engineering, November 08-09, 2002, McLean, Virginia, USA [doi>10.1145/585058.585065]
• 8: P. Grubb and A. Takang. Software Maintenance: Concepts and Practice. World Scientific Publishing Co., Singapore, 2nd edition, 2003.
• 9: HCI. What to put in software maintenance documentation. Available on the Internet at: http://www.hci.com.au/hcisite2/journal/ What to put in software maintenance documentation.htm, 2001--2002. Last accessed on May 27, 2005.
• 10: Shihong Huang , Scott Tilley, Towards a documentation maturity model, Proceedings of the 21st annual international conference on Documentation, October 12-15, 2003, San Francisco, CA, USA [doi>10.1145/944868.944888]
• 11: The State of Documentation Practice within Corrective Maintenance, Proceedings of the IEEE International Conference on Software Maintenance (ICSM'01), p.354, November 07-09, 2001
• 12: Barbara A. Kitchenham , Guilherme H. Travassos , Anneliese von Mayrhauser , Frank Niessink , Norman F. Schneidewind , Janice Singer , Shingo Takada , Risto Vehvilainen , Hongji Yang, Towards an Ontology of software maintenance, Journal of Software Maintenance: Research and Practice, v.11 n.6, p.365-389, Nov. 1999 [doi>10.1002/(SICI)1096-908X(199911/12)11:6<365::AID-SMR200>3.0.CO;2-W ]
• 13: M. Lehman. Programs, life cycles and the laws of software evolution. Proceedings of the IEEE, 68(9):1060--76, sept. 1980.
• 14: Mikael Lindvall , Victor R. Basili , Barry W. Boehm , Patricia Costa , Kathleen Dangle , Forrest Shull , Roseanne Tesoriero , Laurie A. Williams , Marvin V. Zelkowitz, Empirical Findings in Agile Methods, Proceedings of the Second XP Universe and First Agile Universe Conference on Extreme Programming and Agile Methods - XP/Agile Universe 2002, p.197-207, August 04-07, 2002
• 15: Shari Lawrence Pfleeger, Software Engineering: Theory and Practice, Prentice Hall PTR, Upper Saddle River, NJ, 2001
• 16: Vir Phoha, A Standard for Software Documentation, Computer, v.30 n.10, p.97-98, October 1997 [doi>10.1109/2.625327 ]
• 17: Thomas M. Pigoski, Practical Software Maintenance: Best Practices for Managing Your Software Investment, John Wiley & Sons, Inc., New York, NY, 1996
• 18: Charles J. Poole , Allen Higgins, Extreme Maintenance, Proceedings of the IEEE International Conference on Software Maintenance (ICSM'01), p.301, November 07-09, 2001
• 19: Roger S. Pressman, Software Engineering: A Practitioner's Approach, McGraw-Hill Higher Education, 2001
• 20: Václav Rajlich, Incremental Redocumentation Using the Web, IEEE Software, v.17 n.5, p.102-106, September 2000 [doi>10.1109/52.877875 ]
• 21: Robert C. seacord , Daniel Plakosh , Grace A. Lewis, Modernizing Legacy Systems: Software Technologies, Engineering Process and Business Practices, Addison-Wesley Longman Publishing Co., Inc., Boston, MA, 2003
• 22: Bill Thomas , Scott Tilley, Documentation for software engineers: what is needed to aid system understanding?, Proceedings of the 19th annual international conference on Computer documentation, October 21-24, 2001, Sante Fe, New Mexico, USA [doi>10.1145/501516.501570]
• 23: Scott Tilley , Hausi Müller, INFO: a simple document annotation facility, Proceedings of the 9th annual international conference on Systems documentation, p.30-36, October 1991, Chicago, Illinois, United States [doi>10.1145/122778.122784]
• 24: Scott R. Tilley, Documenting-in-the-large vs. documenting-in-the-small, Proceedings of the 1993 conference of the Centre for Advanced Studies on Collaborative research: distributed computing, October 24-28, 1993, Toronto, Ontario, Canada
• 25: Scott R. Tilley , Hausi A. Müller , Mehmet A. Orgun, Documenting software systems with views, Proceedings of the 10th annual international conference on Systems documentation, p.211-219, October 13-16, 1992, Ottawa, Ontario, Canada [doi>10.1145/147001.147033]

INDEX TERMS

Primary Classification:
  D. Software
  D.2 SOFTWARE ENGINEERING
      D.2.0 General

Additional Classification:
  D. Software
  D.2 SOFTWARE ENGINEERING
      D.2.7 Distribution, Maintenance, and Enhancement
          Subjects: Documentation

Keywords:
empirical study, program understanding, software maintenance, software system documentation