Readable computer documentation

ABSTRACT

A retrospective look shows earlier advice still relevant to both predicting and producing readable writing. For prediction, refined readability formulas with stronger criterion passages and updated familiar -word lists have appeared, although the computerization of readability tests sometimes encourages misapplying or misinterpreting them when screening text. For production, attention to sentence construction, word characteristics, and information density remains relevant to both drafting and revising computer documentation for readability, especially since reading speed and reader preference often interact with comprehension in practical settings.

REFERENCES

• 1: Anderson, R. C., and Freebody, P. (1981). Vocabulary knowledge. In J. T. Guthrie (Ed.), Comprehension and teaching: Research reviews (pp. 77-117). Newark, DE: International Reading Association.
• 2: Anderson, R. C., and Freebody, P. (1983). Reading comprehension and the assessment of word knowledge. In B.Hutson (Ed.), Advances in Reading/Language Research, 2 (pp. 231-256). Greenwich, CT: JAI Press.
• 3: Armbruster, B. B. (1984). The problem of inconsiderate text. In G. Duffey (Ed.), Comprehension instruction (pp. 202-217). New York: Longman.
• 4: Barzun, J. (1980). Quotation in The editorial eye, May, 1980.
• 5: Benson, R. W. (1984-1985). The end of legalese: The game is over. Review of Law and Social Change, 13 (3), 519-573.
• 6: Edmund Callis Berkeley, Giant brains; or, Machines that think, John Wiley & Sons, Inc., New York, NY, 1955
• 7: Berkeley, E. C. (1967). Computer-assisted explana-tion. Computers andAutamatian, 16, 32-37.
• 8: Bormuth, J. R. (1966). Readability: A new approach. Reading Research Quarterly, 1, 79-132.
• 9: Brown, W. B. (1965). Science textbook selection and the Dale-Chall formula. School Science and Mathematics, 65, 164-167.
• 10: Calfee, R. C., and Curley, R. (1984). Structures of prose in the content areas. In J. Flood (Ed.), Understanding reading comprehension (pp. 161-180). Newark, DE: International Reading Association.
• 11: Calvin, W. H., and Bickerton, D. (2000). Lingua ex machina. Cambridge, MA: MIT Press.
• 12: Caterpillar Fundamental English (1972, 1976). Pocket reference. Peoria, IL: Caterpillar Tractor Co.
• 13: Chall, J.S., and Dale, E. (1995). Readability revisited: The new Dale-Chall readability formula. Cambridge, MA: Brookline Books.
• 14: Charrow, R. P., and Charrow, V. R. (1979). Making legal language understandable: A psycholinguistic study of jury instructions. Columbia Law Review, 79, 1306-1374.
• 15: Coleman, E. B. (1971). Developing a technology of written instruction: Some determiners of the complexity of prose. In E. Z. Rothkopf and E E. Johnson (Eds.), Verbal learning research and the technology of written instruction (pp. 155-204). New York: Teachers College Press, Columbia University.
• 16: Current Contents. (1988). Social and Behavioral Sciences and Arts and Humanities, 20 (47).
• 17: Dale, E., and Chall, J. S. (1948). A formula for predicting readability. Columbus, OH: Ohio State University Bureau of Educational Research.
• 18: Dale, E., and O'Rourke, J. (1976, 1981). The living word vocabulary. Chicago: World Book/Childcraft International.
• 19: Duffy, T. M. (1985). Readability formulas: What's the use? In T. M. Duffy and R. Waller (Eds.), Designing usable texts (pp. 113-143). Orlando, FL: Academic Press.
• 20: Duffy, T. M., and Kabance, E (1982). Testing a readability approach to text revision. Journal of Educational Psychology, 74, 733-748.
• 21: Entin, E. E., and Klare, G. R. (1985). Relationships of measures of interest, prior knowledge, and readability to comprehension of expository passages. In B. Hutson (Ed.), Advances in Reading~Language Research, 3 (pp. 9-38). Greenwich, CT: JAI Press.
• 22: Ewing, M. J. (1976). A comparison of the effects of readability and time on learning the contents of a state driver's handbook. Unpublished doctoral dissertation, Florida State University.
• 23: Fass, W., and Schumacher, G. M. (1978). Effects of motivation, subject activity, and readability on the retention of prose materials. Journal of Educational Psychology, 70, 803-808.
• 24: Flesch, R. F. (1943). Marks of readable style: A study in adult education. New York: Bureau of Publications, Teachers College, Columbia University.
• 25: Flesch, R. E (1948). A new readability yardstick. Journal of Applied Psychology, 32, 221-233.
• 26: Flower, L. (1985). Problem solving strategies for writing. San Diego, CA: Harcourt, Brace, Jovanovich.
• 27: Flower, L., and Hayes, J. R. (1981). A cognitive process theory of writing. College Composition and Communication, 32, 365-387.
• 28: Flower, L., Hayes, J. R., Care> L., Schriver, K., and Stratman, J. (1986). Detection, diagnosis, and the strategies of revision. College Composition and Communication, 3Z 16-55.
• 29: Fry, E. B. (1977). Fry's readability graph: Clarifications, validity, and extension to level 17. Journal of Reading, 2I, 242-252.
• 30: Fry, E. B. (1989). Readability formulas: Maligned but valid. Journal of Reading, 32, 292-297.
• 31: Greene, M. T. (1979). Effects of readability and directed stopping on the/earning and enjoyment of technical materials. Unpublished doctoral dissertation, University of North Carolina.
• 32: Halliday, M. A. K., and Hasan, R. (1976). Cohesion in English. New York: Longman.
• 33: Holmquist, J. B. (1968). A determination of whether the Dale-Chall readability formula may be revised to evaluate more validly the readability of high school science materials. Unpublished doctoral dissertation, Colorado State University.
• 34: Kemper, S. (1983). Measuring the inference load of a text. Journal of Educational Psychology, 75 (3), 391-401.
• 35: Kemper, S. (1993). Enhancing older adults' reading comprehension. Dkcourse Processes, 16 (4), 405-428.
• 36: Kern, R. (1999). e-mail reply, April 23.
• 37: Kincaid, J. p., and Gamble, L. G. (1977). Ease of comprehension of standard and readable insurance policies as a function of reading ability. Journal of Reading Behavior, 9, 95-87.
• 38: Kintsch, W. (1974). The representation of meaning in memory. Hillsdale, NJ: Erlbaum.
• 39: Kintsch, W., and Vipond, D. (1979). Reading comprehension and readability in educational practice and psychological theory. In L. G. Nilsson (Ed.), Perspectives on memory research (pp. 329-365). Hillsdale, NJ: Erlbaum.
• 40: Klare, G. R. (1963). The measurement of readability. Ames, IA: Iowa State University Press.
• 41: Klare, G. R. (1974-75). Assessing readability. Reading Research Quarterly, i O, 62-102.
• 42: Klare, G. R. (1976). A second look at the validity of readability formulas. Journal of Reading Behavior, & 129-152.
• 43: Klare, G. R. (1979). Readability standards for Armywide publications (Evaluation Report 79-1.). Fort Benjamin Harrison, IN: Directorate of Evaluation, U.S. Army Administration Center.
• 44: Klare, G. R. (1984). Readability. In P. D.Pearson (Ed.), Handbook of reading research (pp. 681-744). New York: Longman.
• 45: Klare, G. R. (1985). How to write readable English. London: Hutchinson.
• 46: Klare, G. R., Mabry, J., and Gustafson, L. M.(1955). The relationship of style difficulty to immediate retention and to acceptability of technical material. Journal of Educational Psychology, 46, 287-295.
• 47: Klare, G. R., Rowe, P. P., St. John, M. G., and Stolurow, L. M. (1969). Automation of the Flesch "Reading Ease" readability formula, with various options. Reading Research Quarterly, 4, 550-559.
• 48: Klare, G. R., Sinaiko, H. W., and Stolurow, L. M. (1972). The cloze procedure: A convenient readability test for training materials and translations. International Review of Applied Psychology, 2i, 77-106.
• 49: Klare, G. R., and Smart, K. L. (1973). Analysis of the readability level of selected USAFI instructional materials. Journal of Educational Research, 67, 176.
• 50: Kling, M., and Pratt, D. E (1977). Readability: A re-examination and new directions for further research. Paper presented at the annual meeting of the National Reading Conference, New Orleans, LA.
• 51: McLaughlin, G. H. (1966). Comparing styles of presenting technical information. Ergonomics, 9, 257-259.
• 52: McLaughlin, G. H. (1969). SMOG grading: A new readability formula. Journal of Reading, i2, 639-646.
• 53: Meyer, B. J. E (1975). Identification of the structure of prose and its implications for the study of reading and memory. Journal of Reading Behavior, Z 7-47.
• 54: Meyer, B. J. E, and Freedle, R. (1984). Effects of discourse type on recall. American Educational Research Journal, 2i, 221-243.
• 55: MIT receives pledge of $350 million to create institute of brain research. (2000). Chronicle of Higher Education, March 10, A-40.
• 56: Moore, A. C. (1935). Recoiling from reading: A consideration of the Thorndike Library. Library Journal, 60, 419-422.
• 57: Murphy, D. R. (1947a). Test proves short words and sentences get best readership. Printer's Ink, 218, 61-64.
• 58: Murphy, D. R. (1947b). How plain talk increases readership 45 percent to 66 per cent. Printer's Ink, 22O, 35-37.
• 59: Nelson, M. J., and Denny, E. C. (1960). The Nelson-Denny Reading Test. Boston: Houghton Mifflin.
• 60: Readability Master 2000. (1997). User's Guide. Cambridge, MA: Brookline Books.
• 61: Redish, J. C., and Seizer, J (1985). The place of readability formulas in technical communication. Technical Communication, 32 (4), 46-52.
• 62: Richards, L. G., and Heller, E P. (1976). Recognition thresholds as a function of word length. American Journal of Psychology, 89, 455-466.
• 63: Rodale, J. I. (1978, 1986). The synonym finder. New York: Warner Books.
• 64: Karen A. Schriver, Dynamics in document design: creating text for readers, John Wiley & Sons, Inc., New York, NY, 1997
• 65: Schumacher, G. M., Klare, G. R., Cronin, E C., and Moses, J. R. (1984). Cognitive activities of beginning and advanced college writers: A pausal analysis. Research in the Teaching of English, i & 169-187.
• 66: Schumacher, G. M., Scott, B. T., Klare, G. R., Cronin, E C., and Lambert, D. A. (1989). Cognitive processes in journalistic genres. Written Communication, 6 (3), 390-407.
• 67: Sinaiko, H. W., and Klare, G. R. (1971). Further experiments in language translation: Readability of computer translations. Paper P-761. Arlington, VA: Institute for Defense Analyses, Science and Technology Division.
• 68: Spache, G. (1974). A new readability formula for primary-grade reading materials. Elementary School Journal, 53, 410-413.
• 69: Stevens, S. S., and Stone, G. (1947). Psychological writing: easy and hard. American Psychologist, 2, 23O-235.
• 70: Swanson, C. C. (1979). Readability and top-level structure: Effects on reading comprehension. Unpublished doctoral dissertation, Arizona State University.
• 71: Tobias, S. (1994). Interest, prior knowledge, and learning. Review of Educational Research, 64 (i), 37-54.
• 72: Waples, D., and Tyler, R. W. (1931). What people want to read about. Chicago: University of Chicago Press.
• 73: Zipf, G. K. (1949). Human behavior and the principle of least effort. Cambridge, MA: Addison-Wesley.

INDEX TERMS

Primary Classification:
  I. Computing Methodologies
  I.7 DOCUMENT AND TEXT PROCESSING
      I.7.5 Document Capture
          Subjects: Document analysis

Additional Classification:
  D. Software
  D.2 SOFTWARE ENGINEERING
      D.2.7 Distribution, Maintenance, and Enhancement
          Subjects: Documentation

  H. Information Systems
  H.1 MODELS AND PRINCIPLES

General Terms:
Design, Documentation, Human Factors, Performance, Theory

Keywords:
comprehension, document drafting, readability formulas