Which documentation for 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 important to them.
KeywordsSource Code Software Maintenance Programming Paradigm Agile Method Software Development Project
- S. W. Ambler. Agile documentation. available on the internet at: http://www.agilemodeling.com/essays/ agile-Documentation.htm, 2001–2005. Last accessed on May 27, 2005.Google Scholar
- 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. InForum of the CAISE, Conference on Advanced Information Systems Engineering (CAiSE’05), jun. 15 2005. accepted for publication.Google Scholar
- L. C. Briand. Software documentation: How much is enough. InProceedings of the Seventh European Conference on Software Maintenance and Reengineering (CSMR’03), pages 13–17. IEEE, IEEE Comp. Soc. Press, March 26–28 2003.Google Scholar
- F. A. Cioch and M. Palazzolo. A documentation suite for maintenance programmers. InProceedings of the 1996 International Conference on Software Maintenance (ICSM’96), pages 286–95. IEEE, IEEE Comp. Soc. Press, Nov 1996.Google Scholar
- A. Forward and T. C. Lethbridge. The relevance of software documentation, tools and technologies: a survey. In DocEng ’02:Proceedings of the 2002 ACM symposium on Document engineering, pages 26–33, New York, NY, USA, 2002. ACM Press.Google Scholar
- 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.Google Scholar
- S. Huang and S. Tilley. Towards a documentation maturity model. In SIGDOC ’03:Proceedings of the 21st annual international conference on Documentation, pages 93–99, New York, NY, USA, 2003. ACM Press.Google Scholar
- M. Kajko-Mattsson. The state of documentation practice within corrective maintenance. InProceedings of the International Conference on Software Maintenance (ICSM’01), pages 354–363. IEEE, IEEE Comp. Soc. Press, Nov. 07–09 2001.Google Scholar
- M. Lindvall, V. R. Basili, B. W. Boehm, P. Costa, K. Dangle, F. Shull, R. Tesoriero, L. A. Williams, and M. V. Zelkowitz. Empirical findings in agile methods. InProceedings of the Second XP Universe and First Agile Universe Conference on Extreme Programming and Agile Methods—XP/Agile Universe 2002, pages 197–207, London, UK, 2002. Springer-Verlag.Google Scholar
- S. L. Pfleeger.Software Engineering: Theory and Practice. Prentice Hall, 2nd edition, 2001.Google Scholar
- T. M. Pigoski.Practical Software Maintenance: Best Practices for Software Investment. John Wiley & Sons, Inc., 1996.Google Scholar
- C. J. Poole, T. Murphy, J. W. Huisman, and A. Higgins. Extreme maintenance. InInternational Conference on Software Maintenance, ICSM’01, pages 301–10. IEEE, IEEE Comp. Soc. Press, Nov. 2001.Google Scholar
- R. S. Pressman.Software Engineering: A Practitioner’s Approach. McGraw-Hill, 5th edition, 2001.Google Scholar
- R. C. Seacord, D. plakosh, and G. A. Lewis.Modernizing Legacy Systems—Software technologies, engineering processes, and business practices. Addison-Wesley, 2003.Google Scholar
- R. van Solingen and E. Berghout.The Goal/Question/Metric Method: A practical guide for quality improvement of software development. McGraw-Hill, 1999.Google Scholar
- M. J. Sousa. A survey on the software maintenance process. InInternational Conference on Software Maintenance, ICSM’98, pages 265–74. IEEE, IEEE Comp. Soc. Press, Mar. 1998.Google Scholar
- V. M. 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.Google Scholar
- B. Thomas and S. Tilley. Documentation for software engineers: what is needed to aid system understanding? InSIGDOC ’01: Proceedings of the 19th annual international conference on Computer documentation, pages 235–236, New York, NY, USA, 2001. ACM Press.Google Scholar
- S. Tilley and H. Müller. Info: a simple document annotation facility. In SIGDOC ’91:Proceedings of the 9th annual international conference on Systems documentation, pages 30–36, New York, NY, USA, 1991. ACM Press.Google Scholar
- S. R. Tilley. Documenting-in-the-large vs. documenting-in-the-small. InProceedings of CASCON’ 93, pages 1083–90. IBM Centre for Advanced Studies, Oct. 1993.Google Scholar
- S. R. Tilley, H. A. Müeller, and M. A. Orgun. Documenting software systems with views. InProceedings of the 10th International Conference on Systems Documentation, SIGDOC’92, pages 211–19. ACM, ACM Press, Oct 1992.Google Scholar
- C. Wohlin, P. Runeson, M. Host, M. C. Ohlsson, B. Regnell, and A. Wesslén.Experimentation in software engineering: an introduction. Kluwer Academic Publishers, 2000. ISBN: 0-7923-8682-5.Google Scholar