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.
This is a preview of subscription content, log in via an institution to check access.
Similar content being viewed by others
References
Adams, E. N. 1984. Optimizing preventive service of software products. IBM J. Res. Dev. 28(1): 2–14.
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.
Arthur, L. J. 1988. Software Evolution: The Software Maintenance Challenge. John Wiley & Sons.
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.
Boehm, B. W. 1981. Software Engineering Economics. Prentice-Hall, pp. 538–540.
Briand, L. C. 2003. Software documentation: How much is enough? Proc. IEEE Int. Conf. Softw. Maint. Reeng. 13–15.
Buican, I. 1990. International English. Proc. IEEE Int. Conf. Prof. Commun. 21712–21714.
Card, D., McGarry, F., and Page, G. 1987. Evaluating software engineering technologies. IEEE Trans. Softw. Eng. 13(7): 845–851.
Carnegie Mellon University and Software Engineering Institute. 1994. The Capability Maturity Model: Guidelines for Improving the Software Process. Addison-Wesley.
Chapin, N. 1985. Software maintenance: A different view. AFIPS Proc. Natl. Comput. Conf. AFIPS Press, Reston, Virginia, 54, pp. 508–513.
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.
Conwell, C. L. 2000. Capability maturity models support of modeling and simulation verification, validation, and accreditation. Proceedings, IEEE Winter Simulation Conference. 819–828.
Cook, C., and Visconti, M. 1994. Documentation is important. CrossTalk 7(11): 26–30.
Delanghe, S. 2000. Using learning styles in software documentation. Proc. IEEE, Transact. Prof. Commun. 201–205.
Edmands, A. 1988. The integrated editor: Involvement of an editor in the entire information development process. Proc. IEEE Int. Prof. Commun. Conf. 119–122.
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.
Hendry, D., et al. 1991. How people use softcopy manuals: A case study. Proc. IEEE Int. Prof. Commun. Conf. 221–224.
Hofmann, P. 1998. Away with words! How to create wordless documentation. Proc. IEEE Int. Prof. Commun. Conf. 437–438.
Hogan, J. M. 2002. The real world software process. Proc. IEEE 9th Asia-Pac. Softw. Eng. Conf. (APSEC'02). 366–375.
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.
IEEE Standards Collection, 1999. Software Engineering. The Institute of Electrical and Electronics Engineers, Inc.
Kane, E. 1984. Doing Your Own Research. Marion Boyars, London & New York.
Kantner, L., et al. 1997. The Best of both worlds: Combining usability testing and documentation projects. Proc. IEEE Int. Prof. Commun. Conf. 355–363.
Kantner, L., et al. 2002. Structured heuristic evaluation of online documentation. Proc. IEEE Int. Prof. Commun. Conf. 331–342.
Kriegsman, M., and Barletta, R. 1993. Building a case-based help desk application. IEEE Expert 8(6): ISSN: 0885–9000, pp. 18–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.
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.
Malcolm, A. 2001. Writing for the disadvantaged reader. Proc. IEEE Int. Conf. Prof. Commun. 95–100.
Martin, J., and McClure, C. 1983. Software Maintenance, The Problem and Its Solutions. Englewood Cliffs, New Jersey: Prentice-Hall, Inc. 07632.
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.
Oskarsson, Ö., and Glass, R. L. 1995. ISO 9000 I Programutveckling - Att Konstruera Kvalitetsprodukter. Studentlitteratur, in Swedish.
Parnas, D. L. 1994. Software aging. Proc. 16th Int. Conf. Softw. Eng. 279–287.
Parnas, D. L. 2000. Requirements documentation: Why a formal basis is essential. Proc. IEEE 4th Int. Conf. Requir. Eng. 81–82.
Parnas, D. L., and Clements, P. C. 1993. A rational design process: How and why to fake it. IEEE Trans. Softw. Eng. 12(2).
Pence, J., and Hon III, S. 1993. Building software quality into telecommunication network systems. Quality Progress. October, 95–97.
Pigoski, T. M. 1997. Practical Software Maintenance. John Wiley & Sons.
Ramsay, J. 1997. Corporate downsizing: Opportunity for a new partnership between engineers and technical writers. Proc. IEEE Int. Prof. Commun. Conf. 399–403.
Rombach, H., and Basili, V. 1987. Quantitative assessment of maintenance: An industrial case study. Proc. IEEE Conf. Softw. Maint. 134–144.
Saunders, P. M. 1989. Communication, semiotics and the mediating role of the technical writer. Proc. IEEE Int. Prof. Commun. Conf. 102–105.
Sousa, M., and Mendes Moreira, H. 1998. A survey of the software maintenance process. Proc. IEEE Conf. Softw. Maint. 265–272.
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.
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.
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.
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.
Walker, R. (ed.) 1985. Applied Qualitative Research. Gower Publishing Company Ltd.
Author information
Authors and Affiliations
Rights and permissions
About this article
Cite this article
Kajko-Mattsson, M. A Survey of Documentation Practice within Corrective Maintenance. Empirical Software Engineering 10, 31–55 (2005). https://doi.org/10.1023/B:LIDA.0000048322.42751.ca
Issue Date:
DOI: https://doi.org/10.1023/B:LIDA.0000048322.42751.ca