Article

A study of the documentation essential to software maintenance

Authors:

Sergio Cozzetti B. de Souza,

Nicolas Anquetil,

Káthia M. de OliveiraAuthors Info & Claims

SIGDOC '05: Proceedings of the 23rd annual international conference on Design of communication: documenting & designing for pervasive information

Pages 68 - 75

https://doi.org/10.1145/1085313.1085331

Published: 21 September 2005 Publication History

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]

M. J. ao Sousa. A survey on the software maintenance process. In International Conference on Software Maintenance, ICSM'98, pages 265--74. IEEE, IEEE Comp. Soc. Press, Mar. 1998.

Digital Library

[5]

L. C. Briand. Software documentation: How much is enough. In Proceedings of the Seventh European Conference on Software Maintenance and Reengineering (CSMR'03), pages 13--17. IEEE, IEEE Comp. Soc. Press, March 26-28 2003.

Digital Library

[6]

F. A. Cioch and M. Palazzolo. A documentation suite for maintenance programmers. In Proceedings of the 1996 International Conference on Software Maintenance (ICSM'96), pages 286--95. IEEE, IEEE Comp. Soc. Press, Nov 1996.

Digital Library

[7]

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.

Digital Library

[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]

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.

Digital Library

[11]

M. Kajko-Mattsson. The state of documentation practice within corrective maintenance. In Proceedings of the International Conference on Software Maintenance (ICSM'01), pages 354--363. IEEE, IEEE Comp. Soc. Press, Nov. 07-09 2001.

Digital Library

[12]

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.

Digital Library

[13]

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

[14]

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

Digital Library

[15]

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

Digital Library

[16]

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

Digital Library

[17]

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

Digital Library

[18]

C. J. Poole, T. Murphy, J. W. Huisman, and A. Higgins. Extreme maintenance. In International Conference on Software Maintenance, ICSM'01, pages 301--10. IEEE, IEEE Comp. Soc. Press, Nov. 2001.

Digital Library

[19]

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

Digital Library

[20]

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

Digital Library

[21]

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

Digital Library

[22]

B. Thomas and S. Tilley. Documentation for software engineers: what is needed to aid system understanding? In SIGDOC '01: Proceedings of the 19th annual international conference on Computer documentation, pages 235--236, New York, NY, USA, 2001. ACM Press.

Digital Library

[23]

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.

Digital Library

[24]

S. R. Tilley. Documenting-in-the-large vs. documenting-in-the-small. In Proceedings of CASCON'93, pages 1083--90. IBM Centre for Advanced Studies, Oct. 1993.

Digital Library

[25]

S. R. Tilley, H. A. Müeller, and M. A. Orgun. Documenting software systems with views. In Proceedings of the 10th International Conference on Systems Documentation, SIGDOC'92, pages 211--19. ACM, ACM Press, Oct 1992.

Digital Library

Cited By

Hickman HBell T(2024)Automated Assessment: Does It Align With Teachers' Views?Proceedings of the 19th WiPSCE Conference on Primary and Secondary Computing Education Research10.1145/3677619.3678113(1-10)Online publication date: 16-Sep-2024
https://dl.acm.org/doi/10.1145/3677619.3678113
Wang HGao ZBi TGrundy JWang XWu MYang X(2024)What Makes a Good TODO Comment?ACM Transactions on Software Engineering and Methodology10.1145/366481133:6(1-30)Online publication date: 28-Jun-2024
https://dl.acm.org/doi/10.1145/3664811
Kallis RColavito GAl-Kaswan APascarella LChaparro ORani PIzadi MDi Sorbo APanichella S(2024)The NLBSE'24 Tool CompetitionProceedings of the Third ACM/IEEE International Workshop on NL-based Software Engineering10.1145/3643787.3648038(33-40)Online publication date: 20-Apr-2024
https://dl.acm.org/doi/10.1145/3643787.3648038
Show More Cited By

Index Terms

A study of the documentation essential to software maintenance
1. Software and its engineering
  1. Software creation and management
    1. Software post-development issues
      1. Documentation

Recommendations

A Survey of Documentation Practice within Corrective Maintenance

The purpose of documentation is to describe software systems and software processes. Consistent, correct and complete documentation of a software system is an important vehicle for the maintainer to gain its understanding, to ease its learning and/or ...
Software maintenance documentation
SIGDOC '89: Proceedings of the 7th annual international conference on Systems documentation

When technical writers speak of software documentation, they usually speak of user manuals. Certainly there is reason for them to. User manuals produced by software people (and I am proud to count myself as a software person!) have often been so bad ...
Documentation for software engineers: what is needed to aid system understanding?
SIGDOC '01: Proceedings of the 19th annual international conference on Computer documentation

Software engineers rely on program documentation as an aid in understanding the functional nature, high-level design, and implementation details of complex applications. However, no one really knows what types of documentation are truly useful to ...

Comments

Information & Contributors

Information

Published In

cover image ACM Conferences

SIGDOC '05: Proceedings of the 23rd annual international conference on Design of communication: documenting & designing for pervasive information

September 2005

176 pages

ISBN:1595931759

DOI:10.1145/1085313

General Chair:
Scott Tilley
Florida Institute of Technology, USA
,
Program Chair:
Robert M. Newman
Coventry University, UK

Copyright © 2005 ACM.

Permission to make digital or hard copies of all or part of this work for personal or classroom use is granted without fee provided that copies are not made or distributed for profit or commercial advantage and that copies bear this notice and the full citation on the first page. Copyrights for components of this work owned by others than ACM must be honored. Abstracting with credit is permitted. To copy otherwise, or republish, to post on servers or to redistribute to lists, requires prior specific permission and/or a fee. Request permissions from [email protected]

Sponsors

Publisher

Association for Computing Machinery

New York, NY, United States

Publication History

Published: 21 September 2005

Permissions

Request permissions for this article.

Request Permissions

Check for updates

Author Tags

Qualifiers

Article

Conference

SIGDOC05

Sponsor:

SIGDOC05: ACM 23rd Annual International Conference on Documentation

September 21 - 23, 2005

Coventry, United Kingdom

Acceptance Rates

Overall Acceptance Rate 355 of 582 submissions, 61%

Contributors

Other Metrics

View Article Metrics

Bibliometrics & Citations

Bibliometrics

Article Metrics

207
Total Citations
View Citations
3,263
Total Downloads

Downloads (Last 12 months)146
Downloads (Last 6 weeks)10

Reflects downloads up to 09 Nov 2024

Other Metrics

View Author Metrics

Citations

Cited By

Hickman HBell T(2024)Automated Assessment: Does It Align With Teachers' Views?Proceedings of the 19th WiPSCE Conference on Primary and Secondary Computing Education Research10.1145/3677619.3678113(1-10)Online publication date: 16-Sep-2024
https://dl.acm.org/doi/10.1145/3677619.3678113
Wang HGao ZBi TGrundy JWang XWu MYang X(2024)What Makes a Good TODO Comment?ACM Transactions on Software Engineering and Methodology10.1145/366481133:6(1-30)Online publication date: 28-Jun-2024
https://dl.acm.org/doi/10.1145/3664811
Kallis RColavito GAl-Kaswan APascarella LChaparro ORani PIzadi MDi Sorbo APanichella S(2024)The NLBSE'24 Tool CompetitionProceedings of the Third ACM/IEEE International Workshop on NL-based Software Engineering10.1145/3643787.3648038(33-40)Online publication date: 20-Apr-2024
https://dl.acm.org/doi/10.1145/3643787.3648038
Oliveira ACorreia JAssunção WPereira Jde Mello RCoutinho DBarbosa CLibório PGarcia A(2024)Understanding Developers’ Discussions and Perceptions on Non-functional Requirements: The Case of the Spring EcosystemProceedings of the ACM on Software Engineering10.1145/36437501:FSE(517-538)Online publication date: 12-Jul-2024
https://dl.acm.org/doi/10.1145/3643750
Messer MBrown NKölling MShi M(2024)Automated Grading and Feedback Tools for Programming Education: A Systematic ReviewACM Transactions on Computing Education10.1145/363651524:1(1-43)Online publication date: 19-Feb-2024
https://dl.acm.org/doi/10.1145/3636515
Sun WFang CChen YZhang QTao GYou YHan TGe YHu YLuo BChen Z(2024)An Extractive-and-Abstractive Framework for Source Code SummarizationACM Transactions on Software Engineering and Methodology10.1145/363274233:3(1-39)Online publication date: 14-Mar-2024
https://dl.acm.org/doi/10.1145/3632742
Feng LYen RYou YFan MZhao JLu Z(2024)CoPrompt: Supporting Prompt Sharing and Referring in Collaborative Natural Language ProgrammingProceedings of the 2024 CHI Conference on Human Factors in Computing Systems10.1145/3613904.3642212(1-21)Online publication date: 11-May-2024
https://dl.acm.org/doi/10.1145/3613904.3642212
Fang CSun WChen YChen XWei ZZhang QYou YLuo BLiu YChen Z(2024)Esale: Enhancing Code-Summary Alignment Learning for Source Code SummarizationIEEE Transactions on Software Engineering10.1109/TSE.2024.342227450:8(2077-2095)Online publication date: Aug-2024
https://doi.org/10.1109/TSE.2024.3422274
Xu ZGuo SWang YChen RLi HLi XJiang H(2024)Code Comment Inconsistency Detection Based on Confidence LearningIEEE Transactions on Software Engineering10.1109/TSE.2024.335848950:3(598-617)Online publication date: Mar-2024
https://doi.org/10.1109/TSE.2024.3358489
Liang HHuang C(2024)Integrating Non-Fourier and AST-Structural Relative Position Representations Into Transformer-Based Model for Source Code SummarizationIEEE Access10.1109/ACCESS.2024.335439012(9871-9889)Online publication date: 2024
https://doi.org/10.1109/ACCESS.2024.3354390
Show More Cited By

View Options

Get Access

Login options

Check if you have access through your login credentials or your institution to get full access on this article.

Full Access

Get this Publication

View options

PDF

View or Download as a PDF file.

eReader

View online with eReader.

Media

Figures

Other

Tables

View Table of Contents