Deborah A. Boehm-Davis
ABSTRACT
A complete software package always includes documentation. Although its importance is often overlooked, documentation may be the only source of program design information. Major tasks in the software life cycle, such as design, coding, testing and maintenance, are often performed by different individuals. Lientz and Swanson (1979) found that, typically, only about half of a software system's maintenance personnel had been involved in its development. Poor documentation techniques can, therefore, dramatically increase labor costs throughout the labor intensive software life cycle by making both development and maintenance tasks more difficult.
Recent research in this area (Boehm-Davis, Sheppard, & Bailey, 1982; Sheppard, Kruesi, & Bailey, in press; Sheppard, Kruesi, & Curtis, 1981) has been directed toward determining performance on a set of software tasks as a function of the type of documentation. In these studies, programmer performance was examined on comprehension, coding, debugging, and modification tasks as a function of the type of documentation provided. The documentation formats were constructed from the factorial combination of three types of symbology with three types of spatial arrangement. These formats were chosen because they represent the primary dimensions for categorizing the way in which available documentation aids configure the information they present to programmers (Jones, 1979). The three types of symbology in which information was presented consisted of normal English, abbreviated English (such as program design language), and ideograms. The spatial arrangements of the information used in these experiments were sequential, branching, and hierarchical. While each of the four tasks pursued in this research produced slightly different results, there was a general trend towards the superiority of succinct symbology and a branching spatial arrangement in each.
- 1.Boehm-Davis, D. A., Sheppard, S. B., & Bailey, J. W. An empirical evaluation of language-tailored PDLs. In Proceedings of the 26th Annual Meeting of the Human Factors Society. Santa Monica, CA: The Human Factors Society, 1982, 984-988.Google Scholar
Cross Ref
- 2.Davies, O. L. The design and analysis of industrial experiments. Oliver & Boyd, 1956.Google Scholar
- 3.Jones, C. A survey of programming design and specification techniques. In Proceedings of the IEEE Conference on Specifications of Reliable Software. New York: IEEE, 1979.Google Scholar
- 4.Lientz, B. P. & Swanson, E. G. The use of productivity aids in system development and maintenance (Technical Report 79-1). Los Angeles, CA: UCLA, Graduate School of Management, 1979.Google Scholar
- 5.McCabe, T. J. A complexity measure. IEEE Transactions on Software Engineering, 1976, 2, 308-320.Google ScholarDigital Library
- 6.Sheppard, S. B., Kruesi, E., & Bailey, J.W. An empirical evaluation of software documentation formats. In J. Thomas, & M. Schneider (Eds.), Human Factors in Computer Systems. Norwood, NJ: Ablex Publishing Corp., in press. Google ScholarDigital Library
- 7.Sheppard, S. B., Kruesi, E., & Curtis, B. The effects of symbology and spatial arrangement on the comprehension of software specifications. In Proceedings of the Fifth International Conference on Software Engineering, San Diego, CA: IEEE, 1981. Google ScholarDigital Library
- 8.Winer, B. J. Statistical principles in experimental design. New York: McGraw-Hill, 1971.Google Scholar
Index Terms
- Documentation of concurrent programs
Recommendations
Documentation threads - presentation of fragmented documentation
In this paper, we introduce a means for presenting fragmented documentation through a concept called documentation threads. A documentation thread presents a number of documentation fragments specified by the programmer and can guide a documentation ...
Code Documentation
The basic principles of good code documentation include the avoidance of repetition, the coexistence of code and its documentation, the documentation of all artifacts, and a preference for clear code and automated processes to explanatory documentation. ...
Precise Documentation of Well-Structured Programs
Describes a new form of program documentation that is precise, systematic and readable. This documentation comprises a set of displays supplemented by a lexicon and an index. Each display presents a program fragment in such a way that its correctness ...
Comments