Advertisement

Empirical Software Engineering

, Volume 10, Issue 1, pp 31–55 | Cite as

A Survey of Documentation Practice within Corrective Maintenance

  • Mira Kajko-Mattsson
Article

Abstract

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 relearning processes, and to make the system more maintainable. Poor system documentation, on the other hand, is the primary reason for quick software system quality degradation and ageing. Proper process documentation records the process, its stages and tasks, executing roles, their decisions and motivations, and the results of each individual process task. It is extremely important for achieving insight and visibility into the processes, important for their meaningful process measurement and thereby pivotal for achieving high process maturity. In this paper, we report on the results of an explorative study in which we have identified a number of rudimentary documentation requirements relevant within corrective maintenance, and found out how they were implemented within eighteen software organizations in Sweden. The goal was to examine the industrial documentation practice within corrective maintenance. Our results show that the documentation within corrective maintenance is still a very neglected issue within the organisations studied. None of our organisations has fully implemented all our documentation requirements.

Corrective maintenance software system documentation software process documentation 

Preview

Unable to display preview. Download preview PDF.

Unable to display preview. Download preview PDF.

References

  1. Adams, E. N. 1984. Optimizing preventive service of software products. IBM J. Res. Dev. 28(1): 2–14.Google Scholar
  2. Antoniol, G., Canfora, G., Casazza, G., and De Lucia, A. 2000. Information retrieval models for recovering traceability links between code and documentation. Proc. IEEE Int. Conf. Softw. Maint. 40–49.Google Scholar
  3. Arthur, L. J. 1988. Software Evolution: The Software Maintenance Challenge. John Wiley & Sons.Google Scholar
  4. Bauer, B. J., and Parnas, D. L. 1995. Applying mathematical software documentation: An experience report, proceedings. Proc. 10th Annual Conference on Computer Assurance. 273–284.Google Scholar
  5. Boehm, B. W. 1981. Software Engineering Economics. Prentice-Hall, pp. 538–540.Google Scholar
  6. Briand, L. C. 2003. Software documentation: How much is enough? Proc. IEEE Int. Conf. Softw. Maint. Reeng. 13–15.Google Scholar
  7. Buican, I. 1990. International English. Proc. IEEE Int. Conf. Prof. Commun. 21712–21714.Google Scholar
  8. Card, D., McGarry, F., and Page, G. 1987. Evaluating software engineering technologies. IEEE Trans. Softw. Eng. 13(7): 845–851.Google Scholar
  9. Carnegie Mellon University and Software Engineering Institute. 1994. The Capability Maturity Model: Guidelines for Improving the Software Process. Addison-Wesley.Google Scholar
  10. Chapin, N. 1985. Software maintenance: A different view. AFIPS Proc. Natl. Comput. Conf. AFIPS Press, Reston, Virginia, 54, pp. 508–513.Google Scholar
  11. Clark, P. G., Lobsitz, R. M., and Shields, J. D. 1989. Documenting the evolution of an information system. Proc. IEEE Natl. Aerosp. Electr. Conf. 1819–1826.Google Scholar
  12. Conwell, C. L. 2000. Capability maturity models support of modeling and simulation verification, validation, and accreditation. Proceedings, IEEE Winter Simulation Conference. 819–828.Google Scholar
  13. Cook, C., and Visconti, M. 1994. Documentation is important. CrossTalk 7(11): 26–30.Google Scholar
  14. Delanghe, S. 2000. Using learning styles in software documentation. Proc. IEEE, Transact. Prof. Commun. 201–205.Google Scholar
  15. Edmands, A. 1988. The integrated editor: Involvement of an editor in the entire information development process. Proc. IEEE Int. Prof. Commun. Conf. 119–122.Google Scholar
  16. El Emam, K., Drouin, J-N., and Melo, W. 1998. SPICE: The Theory and Practice of Software Process Improvement and Capability Determination. IEEE Computer Society Press.Google Scholar
  17. Hendry, D., et al. 1991. How people use softcopy manuals: A case study. Proc. IEEE Int. Prof. Commun. Conf. 221–224.Google Scholar
  18. Hofmann, P. 1998. Away with words! How to create wordless documentation. Proc. IEEE Int. Prof. Commun. Conf. 437–438.Google Scholar
  19. Hogan, J. M. 2002. The real world software process. Proc. IEEE 9th Asia-Pac. Softw. Eng. Conf. (APSEC'02). 366–375.Google Scholar
  20. Holt, P. O. 1993. System documentation and system design: A good reason for designing the manual first. Proc. IEEE Colloquium on Issues in Computer Support for Documentation and Manuals. 1/1–1/3.Google Scholar
  21. IEEE Standards Collection, 1999. Software Engineering. The Institute of Electrical and Electronics Engineers, Inc.Google Scholar
  22. Kane, E. 1984. Doing Your Own Research. Marion Boyars, London & New York.Google Scholar
  23. Kantner, L., et al. 1997. The Best of both worlds: Combining usability testing and documentation projects. Proc. IEEE Int. Prof. Commun. Conf. 355–363.Google Scholar
  24. Kantner, L., et al. 2002. Structured heuristic evaluation of online documentation. Proc. IEEE Int. Prof. Commun. Conf. 331–342.Google Scholar
  25. Kriegsman, M., and Barletta, R. 1993. Building a case-based help desk application. IEEE Expert 8(6): ISSN: 0885–9000, pp. 18–26.Google Scholar
  26. Lepasaar, M., Varkoi, T., and Jaakkola, H. 2001. Documentation as a software process capability indicator. Proc. IEEE Int. Conf. Manage. Eng. Technol. 1, pp. 436.Google Scholar
  27. Lientz, B. P., and Swanson, E. B. 1980. Software Maintenance Management, A study of the Maintenance of Computer Application Software in 487 Data Processing Organizations. Addison-Wesley.Google Scholar
  28. Malcolm, A. 2001. Writing for the disadvantaged reader. Proc. IEEE Int. Conf. Prof. Commun. 95–100.Google Scholar
  29. Martin, J., and McClure, C. 1983. Software Maintenance, The Problem and Its Solutions. Englewood Cliffs, New Jersey: Prentice-Hall, Inc. 07632.Google Scholar
  30. Norman, R. L., and Holloran, R. W. 1991. How to simplify the structure of administrative procedures to make them easier to write, review, produce, and use. Proc. Int. Conf. Prof. Commun. 2, pp. 447–450.Google Scholar
  31. Oskarsson, Ö., and Glass, R. L. 1995. ISO 9000 I Programutveckling - Att Konstruera Kvalitetsprodukter. Studentlitteratur, in Swedish.Google Scholar
  32. Parnas, D. L. 1994. Software aging. Proc. 16th Int. Conf. Softw. Eng. 279–287.Google Scholar
  33. Parnas, D. L. 2000. Requirements documentation: Why a formal basis is essential. Proc. IEEE 4th Int. Conf. Requir. Eng. 81–82.Google Scholar
  34. Parnas, D. L., and Clements, P. C. 1993. A rational design process: How and why to fake it. IEEE Trans. Softw. Eng. 12(2).Google Scholar
  35. Pence, J., and Hon III, S. 1993. Building software quality into telecommunication network systems. Quality Progress. October, 95–97.Google Scholar
  36. Pigoski, T. M. 1997. Practical Software Maintenance. John Wiley & Sons.Google Scholar
  37. Ramsay, J. 1997. Corporate downsizing: Opportunity for a new partnership between engineers and technical writers. Proc. IEEE Int. Prof. Commun. Conf. 399–403.Google Scholar
  38. Rombach, H., and Basili, V. 1987. Quantitative assessment of maintenance: An industrial case study. Proc. IEEE Conf. Softw. Maint. 134–144.Google Scholar
  39. Saunders, P. M. 1989. Communication, semiotics and the mediating role of the technical writer. Proc. IEEE Int. Prof. Commun. Conf. 102–105.Google Scholar
  40. Sousa, M., and Mendes Moreira, H. 1998. A survey of the software maintenance process. Proc. IEEE Conf. Softw. Maint. 265–272.Google Scholar
  41. van Schouwen, A. J., Parnas, D. L., and Madey, J. 1993. Documentation of requirements for computer systems. Proc. IEEE Int. Symp. Requir. Eng. 198–207.Google Scholar
  42. Visaggio, G. 2001. Aging of a data-intensive legacy system: Symptoms and remedies. Journal of Software Maintenance and Evolution: Research and Practice. Wiley & Sons, 13(5): 281–308.Google Scholar
  43. Visconti, M., and Cook, C. R. 2000. An overview of industrial software documentation practices. Technical Report 00–60–06, Computer Science Department, Oregon State University, April.Google Scholar
  44. Visconti, M., and Cook, C. R. 2002. An overview of industrial software documentation practice. Proc. 12th IEEE Int. Conf. Chilean Comput. Sci. Soc. 179–186.Google Scholar
  45. Walker, R. (ed.) 1985. Applied Qualitative Research. Gower Publishing Company Ltd.Google Scholar

Copyright information

© Springer Science + Business Media, Inc. 2005

Authors and Affiliations

  • Mira Kajko-Mattsson
    • 1
  1. 1.Software Maintenance Laboratory, Department of Computer and Systems SciencesStockholm University, Royal Institute of Technology, and IT UniversitySweden

Personalised recommendations