Andrew Forward
Timothy C. Lethbridge
ABSTRACT
This paper highlights the results of a survey of software professionals. One of the goals of this survey was to uncover the perceived relevance (or lack thereof) of software documentation, and the tools and technologies used to maintain, verify and validate such documents. The survey results highlight the preferences for and aversions against software documentation tools. Participants agree that documentation tools should seek to better extract knowledge from core resources. These resources include the system's source code, test code and changes to both. Resulting technologies could then help reduce the effort required for documentation maintenance, something that is shown to rarely occur. Our data reports compelling evidence that software professionals value technologies that improve automation of the documentation process, as well as facilitating its maintenance.
- Ambler, Scott and Ron Jeffries. Agile Modelling: Effective Practices for Extreme Programming and the Unified Process, John Wiley & Sons, 2002, chapter 14. Google Scholar
Digital Library
- Ambler, Scott. The Fragile Manifesto, Software Development, August 2002.Google Scholar
- Berglund E. (2000) Writing for Adaptable Documentation, IPCC/SIGDOC 2000, September 24-27, Cambridge, Massachusetts, p497--508. Google ScholarDigital Library
- Cockburn, A. Agile Software Development, Addison-Wesley Pub Co, 2001. Google ScholarDigital Library
- Curtis Bill, et al. A field study of the software design process for large systems. Communications of the ACM, Volume 31, Number 11, November 1988, p1268--1287. Google ScholarDigital Library
- Forward, A. Software Documentation - Building and Maintaining Artefacts of Communication. Thesis submission available online at {7}.Google Scholar
- Forward, A. Survey data website available at www.site.uottawa.ca/~aforward/docsurvey/Google Scholar
- Glass, R. Software maintenance documentation, SIGDOC '89, Pittsburg, Pennsylvania, USA, ACM Press, p18--23.Google Scholar
- Institute of Phonetic Sciences (IFA). http://fonsg3.let.uva.nl/Service/Statistics/RankCorrelation_coefficient.htmlGoogle Scholar
- Jazzar, Abdulaziz and Walt Scacchi. Understanding the requirements for information system documentation: an empirical investigation, COOCS `95, Sheraton Silicon Valley, California, USA, ACM Press, p268--279. Google ScholarDigital Library
- Kleinberg, J. Authoritative sources in a hyperlinked environment. Proc. 9th ACM-SIAM Symposium on Discrete Algorithms, 1998. Google ScholarDigital Library
- Medina, Enrique Arce. Some aspects of software documentation, SIGDOC '84, Mexico City, Mexico, p57--59. Google ScholarDigital Library
- Ouchi, Miheko L. Software Maintenance Documentation, SIGDOC'85, New York, USA, ACM Press, p18--23. Google ScholarDigital Library
- Scheff, Benson H. and Tom Georgon. Letting software engineers do software engineering or freeing software engineers from the shackles of documentation. SIGDOC '88, Ann Arbor, Michigan, USA, ACM Press, p81--91. Google ScholarDigital Library
- Thomas, Bill and Scott Tilley. Documentation for software engineers: what is needed to aid system understanding?, SIGODC '01, Sante Fe, New Mexico, USA, p 235--236. Google ScholarDigital Library
Index Terms
- The relevance of software documentation, tools and technologies: a survey
Recommendations
A study of documentation for software architecture
AbstractDocumentation is an important mechanism for disseminating software architecture knowledge. Software project teams can employ vastly different formats for documenting software architecture, from unstructured narratives to standardized documents. We ...
Automating testing by reverse engineering of software documentation
WCRE '95: Proceedings of the Second Working Conference on Reverse EngineeringReverse engineering of software documentation can play an important role in automating software testing. Since testers often compare the operation of a software system to the expected behavior as described in a document, information extraction from ...
Documenting software systems with views
SIGDOC '92: Proceedings of the 10th annual international conference on Systems documentationSoftware professionals rely on internal documentation as an aid in understanding programs. Unfortunately, the documentation for most programs is usually out-of-date and cannot be trusted. Without it, the only reliable and objective information is the ...
Comments