Skip to main content
Journal of the Brazilian Computer Society
Download PDF

Which documentation for software maintenance?

Journal of the Brazilian Computer Society volume 12, pages 31–44 (2006)Cite this article

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 important to them.

References

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. P. Grubb and A. Takang.Software Maintenance: Concepts and Practice. World Scientific Publishing Co., Singapore, 2nd edition, 2003.

    Book  MATH  Google Scholar 

  7. 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.

  8. 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.

  9. 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.

  10. B. A. Kitchenham, G. H. Travassos, A. von Mayrhauser, F. Niessink, N. F. Schneidewind, J. Singer, S. Takada, R. Vehvilainen, and H. Yang. Towards an ontology of software maintenance.Journal of Software Maintenance: Research and Practice, 11:365–389, 1999.

    Article  Google Scholar 

  11. M. Lehman. Programs, life cycles and the laws of software evolution.Proceedings of the IEEE, 68(9):1060–76, sept. 1980.

    Article  Google Scholar 

  12. 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.

  13. S. L. Pfleeger.Software Engineering: Theory and Practice. Prentice Hall, 2nd edition, 2001.

  14. V. Phoha. A standard for software documentation.Computer, 30(10):97–98, Oct. 1997.

    Article  Google Scholar 

  15. T. M. Pigoski.Practical Software Maintenance: Best Practices for Software Investment. John Wiley & Sons, Inc., 1996.

  16. 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.

  17. R. S. Pressman.Software Engineering: A Practitioner’s Approach. McGraw-Hill, 5th edition, 2001.

  18. V. Rajlich. Incremental redocumentation using the web.IEEE Software, 17(5):102–6, Sep 2000.

    Article  Google Scholar 

  19. R. C. Seacord, D. plakosh, and G. A. Lewis.Modernizing Legacy Systems—Software technologies, engineering processes, and business practices. Addison-Wesley, 2003.

  20. R. van Solingen and E. Berghout.The Goal/Question/Metric Method: A practical guide for quality improvement of software development. McGraw-Hill, 1999.

  21. 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.

  22. 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 

  23. 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.

  24. 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.

  25. 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.

  26. 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.

  27. 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.

Download references

Author information

Authors and Affiliations

  1. UCB - Catholic University of Brasilia, SGAN 916 Môdulo B - Av. W5 Norte, 70.790-160, Brasília, DF, Brazil

    Sergio Cozzetti B. de Souza, Nicolas Anquetil & Káthia M. de Oliveira

Authors
  1. Sergio Cozzetti B. de Souza
    View author publications

    You can also search for this author in PubMed Google Scholar

  2. Nicolas Anquetil
    View author publications

    You can also search for this author in PubMed Google Scholar

  3. Káthia M. de Oliveira
    View author publications

    You can also search for this author in PubMed Google Scholar

Rights and permissions

Open Access This article is distributed under the terms of the Creative Commons Attribution 2.0 International License ( https://creativecommons.org/licenses/by/2.0 ), which permits unrestricted use, distribution, and reproduction in any medium, provided the original work is properly cited.

Reprints and permissions

About this article

Cite this article

de Souza, S.C.B., Anquetil, N. & de Oliveira, K.M. Which documentation for software maintenance?. J Braz Comp Soc 12, 31–44 (2006). https://doi.org/10.1007/BF03194494

Download citation

  • Issue Date:

  • DOI: https://doi.org/10.1007/BF03194494

Keywords