Software documentation is a growing field in technical writing, yet no synthesis of current research exists to bring together findings on content, form, and the invoked relationship between reader and writer. Without such an overview writers are apt to follow discrete, context-free prescriptions instead of guiding principles that account for the multidimensional functions of language in the communication act of a user's manual. This article reviews findings from research in cognitive processing and text linguistics to derive such a set of principles. It then assesses a widely-used wordprocessing manual against these principles to find that the writers manipulate form (the textual function of language) to achieve comprehension better than they do content (the ideational function) or reader-writer relationships (the interpersonal function). However, comprehension is stymied without equal attention paid to ideational and interpersonal strategies.
Get full access to this article
View all access options for this article.
References
1.
FraseL., Effects of Semantic Incompatibility Upon Deductive Reasoning, Psychonomic Science, 12, p. 64, 1968.
2.
HallidayM. A. K., Explorations in the Function of Language, Edward Arnold, London, 1973.
3.
KierasD., The Role of Prior Knowledge in Operating Equipment from Written Instructions, Report No. 19, Personnel and Training Research Programs, Office of Naval Research, Arlington, 1985.
4.
KierasD. and BovairS., The Acquisition of Procedures from Text: A Production-System Analysis of Transfer of Training, Report No. 16, Personnel and Training Research Programs, Office of Naval Research, Arlington, 1985.
5.
KierasD. and PoisonP., An Approach to the Formal Analysis of User Complexity, Working Paper No. 2, 1982.
6.
NormanD.GentnerD., and StevensA., Comments on Learning Schemata and Memory Representation, in Cognition and Instruction, KlahrD. (ed.), Lawrence Erlbaum Associates, Hillsdale, New Jersey, 1976.
7.
SimonH. and HayesJ., Understanding Complex Instructions, in Cognition and Instruction, KlahrD. (ed.), Lawrence Erlbaum Associates, Hillsdale, New Jersey, 1976.
8.
deBeaugrandeR., Text, Discourse and Process: Toward a Multidisciplinary Science of Texts, Ablex Publishing Company, Norwood, New Jersey, 1980.
9.
WrightP. and ReidF., Written Information: Some Alternatives to Prose for Expressing the Outcomes of Complex Contingencies, Journal of Applied Psychology, 57, pp. 160–166, 1973.
10.
WrightP., Presenting Technical Information: A Survey of Research Findings, Instructional Science, 6:1, pp. 93–134, 1977.
11.
FlowerL.HayesJ., and SwartzH., Revising Functional Documents: The Scenario Principle, in New Essays in Technical and Scientific Communication: Research, Theory and Practice, Volume 2, AndersonP.BrockmanR. J., and MillerC. (eds.), Baywood Publishing Company, Farmingdale, New York, 1983.
12.
SelzerJ., What Constitutes a “Readable” Technical Style, in New Essays in Technical and Scientific Communication, AndersonP.BrockmanR. J., and MillerC. (eds.), Baywood Publishing Company, Farmingdale, New York, 1983.
13.
deBeaugrandeR., Communication in Technical Communication, Journal of Technical Writing and Communication, 8:1, pp. 5–15, 1978.
14.
CharrowR. and CharrowV., Making Legal Language Understandable: A Psycholinguistic Study of Jury Instructions, Columbia Law Review, 79:2, pp. 1306–1379, 1979.
15.
HollandY. M. and RoseA., Understanding Instructions with Complex Conditions, Document Design Report, Technical Report No. 5, American Institutes for Research, Washington, D.C., 1980.
16.
JustM. and CarpenterP., Verbal Comprehension in Instructional Situation, in Cognition and Instruction, KhlarD. (ed.), Lawrence Erlbaum Associates, Hillsdale, New Jersey, 1976.
17.
WrightP., Feeding the Information-Eaters: Suggestions for Integrating Pure and Applied Research in Language Comprehension, Instructional Science, 7, pp. 249–312, 1978.
18.
CarpenterP. and JustM., Eye Fixations and Comprehension, in Cognitive Processes in Comprehension, JustM. and CarpenterP. (eds.), Lawrence Erlbaum Associates, Hillsdale, New Jersey, 1977.
19.
HornR., How to Write Information Mapping, Information Resources, Inc., Lexington, Massachusetts, 1976.
20.
DuffyT.CurranT., and SassD., Document Design for Technical Job Tasks: An Evaluation, Human Factors, 25, pp. 143–160, 1983.
21.
HartleyJ., Eighty Ways of Improving Instructional Text, IEEE Transactions of Professional Communication, Pc-24:1, pp. 17–27, 1981.
22.
FelkerD.PickeringF.CharrowV.HollandV. M., and RedishJ., Guidelines for Document Designers, Document Design Project, American Institutes for Research, Washington, D.C., 1981.
23.
OlsenL. and HuckinT., Principles of Communication for Science and Technology, McGraw Hill, New York, 1983.
24.
StevensonD. and MathesJ. C., Designing Technical Reports: Writing for Audiences in Organizations, Bobbs Merrill Book Company, Indianapolis, 1976.
25.
SanfordA. and GarradS., Towards a Processing Account of Reference, in Discourse Processing, FlammerA. and KintschW. (eds.), North-Holland Publishing Company, Amsterdam, 1982.
26.
WinogradT., Understanding Discourse, in Cognitive Processes in Comprehension, CarpenterP. and JustM. (eds.), Lawrence Erlbaum Associates, Hillsdale, New Jersey, 1977.
27.
RiderP., Superwylbur User Guide, Northern Illinois University, 1981.
28.
Microsoft Word for the Apple Macintosh, Microsoft Corporation, Bellevue, WA., 1984.
29.
ShuyR. and LarkinD., Linguistic Considerations in the Simplification/Clarification of Insurance Policy Language, Discourse Processes, 1, pp. 305–321, 1978.
30.
SelzerJ., Certain Cohesion Elements and the Readability of Technical Paragraphs, Journal of Technical Writing and Communication, 12:4, pp. 285–300, 1982.
31.
ThorndykeP. and Hayes-RothB., Integration of Knowledge from a Text, Journal of Verbal Language and Verbal Behavior, 18:1, pp. 91–108, 1979.
32.
van DijkT. A., Opinions and Attitudes in Discourse Comprehension, in Language and Comprehension, Le NyJ. and KintschW. (eds.), North-Holland Publishing Company, Amsterdam, 1982.
33.
AuldR.LangK., and LangT., University Computer Users: Characteristic and Behavior, in Computing Skills and the User Interface, CoombsM. J. and AltyJ. L. (eds.), Academic Press, London, 1981.
34.
ShuchmanH., Information Transfer in Engineering, The Futures Group, Glastonbury, Connecticut, 1981.
35.
EasonK. D. and DamodaranL., The Needs of the Commercial User, in Computing Skills and the User Interface, CoombsM. J. and AltyJ. L. (eds.), Academic Press, London, 1981.
36.
FishS., Is There a Text in the Class?Harvard University Press, Cambridge, 1980.
37.
WhiteJ., When Words Lose Their Meaning, University of Chicago Press, Chicago, 1984.
38.
FoxD., TEXTEDIT, University of Michigan, Ann Arbor, 1981.
39.
FowlerR.HodgeB.KressG., and TrewT., Language and Control, Routledge and Kegan Paul, London, 1979.
