Journal of the Brazilian Computer Society

, Volume 12, Issue 3, pp 31–44 | Cite as

Which documentation for software maintenance?

  • Sergio Cozzetti B. de Souza
  • Nicolas Anquetil
  • Káthia M. de Oliveira
Open Access


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.


Source Code Software Maintenance Programming Paradigm Agile Method Software Development Project 
These keywords were added by machine and not by the authors. This process is experimental and the keywords may be updated as the learning algorithm improves.


  1. [1]
    S. W. Ambler. Agile documentation. available on the internet at: agile-Documentation.htm, 2001–2005. Last accessed on May 27, 2005.Google Scholar
  2. [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.Google Scholar
  3. [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.Google Scholar
  4. [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.Google Scholar
  5. [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.Google Scholar
  6. [6]
    P. Grubb and A. Takang.Software Maintenance: Concepts and Practice. World Scientific Publishing Co., Singapore, 2nd edition, 2003.MATHCrossRefGoogle Scholar
  7. [7]
    HCI. What to put in software maintenance documentation. Available on the Internet at: What to put in software maintenance documentation. htm, 2001–2002. Last accessed on May 27, 2005.Google Scholar
  8. [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.Google Scholar
  9. [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.Google Scholar
  10. [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.CrossRefGoogle Scholar
  11. [11]
    M. Lehman. Programs, life cycles and the laws of software evolution.Proceedings of the IEEE, 68(9):1060–76, sept. 1980.CrossRefGoogle Scholar
  12. [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.Google Scholar
  13. [13]
    S. L. Pfleeger.Software Engineering: Theory and Practice. Prentice Hall, 2nd edition, 2001.Google Scholar
  14. [14]
    V. Phoha. A standard for software documentation.Computer, 30(10):97–98, Oct. 1997.CrossRefGoogle Scholar
  15. [15]
    T. M. Pigoski.Practical Software Maintenance: Best Practices for Software Investment. John Wiley & Sons, Inc., 1996.Google Scholar
  16. [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.Google Scholar
  17. [17]
    R. S. Pressman.Software Engineering: A Practitioner’s Approach. McGraw-Hill, 5th edition, 2001.Google Scholar
  18. [18]
    V. Rajlich. Incremental redocumentation using the web.IEEE Software, 17(5):102–6, Sep 2000.CrossRefGoogle Scholar
  19. [19]
    R. C. Seacord, D. plakosh, and G. A. Lewis.Modernizing Legacy Systems—Software technologies, engineering processes, and business practices. Addison-Wesley, 2003.Google Scholar
  20. [20]
    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
  21. [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.Google Scholar
  22. [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. [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.Google Scholar
  24. [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.Google Scholar
  25. [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.Google Scholar
  26. [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.Google Scholar
  27. [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.Google Scholar

Copyright information

© The Brazilian Computer Society 2007

Authors and Affiliations

  • Sergio Cozzetti B. de Souza
    • 1
  • Nicolas Anquetil
    • 1
  • Káthia M. de Oliveira
    • 1
  1. 1.UCB - Catholic University of BrasiliaBrasíliaBrazil

Personalised recommendations