Citation
A discourse analysis of software documentation

Material Information

Title:
A discourse analysis of software documentation what's working
Creator:
Walters, Nancy James
Publication Date:
Language:
English
Physical Description:
viii, 142 leaves : ; 29 cm

Subjects

Subjects / Keywords:
Software documentation ( lcsh )
Electronic data processing documentation ( lcsh )
Electronic data processing documentation ( fast )
Software documentation ( fast )
Genre:
bibliography ( marcgt )
theses ( marcgt )
non-fiction ( marcgt )

Notes

General Note:
Submitted in partial fulfillment of the requirements for the degree, Master of Science in Technical Communication, Dept. of English.
Statement of Responsibility:
Nancy James Walters.

Record Information

Source Institution:
University of Colorado Denver
Holding Location:
Auraria Library
Rights Management:
All applicable rights reserved by the source institution and holding location.
Resource Identifier:
22927355 ( OCLC )
ocm22927355
Classification:
LD1190.L67 1990m .W34 ( lcc )

Downloads

This item is only available as the following downloads:


Full Text

PAGE 1

A DISCOURSE ANALYSIS OF SOFTWARE DOCUMENTATION: WHAT'S WORKING by Nancy James Walters B.A., Montclair State College, 1963 A thesis submitted to the Faculty of the Graduate School of the University of Colorado-in partial fulfillment of therequirements for the degree of Master of Science in Technical Commtini"cation Department of English 1990

PAGE 2

This thesis for the Master of Science in Technical Communication degree by Nancy James Walters has been approved for the Department of English by Charles C. Beck P. Schneider Brent Wilson 3 cJ A c;; a Date

PAGE 3

Walters, Nancy James (M.S.T.C., Department of English) A Discourse Analysis of Software Documentation: What's Working Thesis directed by Associate Professor Charles c. Beck The demand for software documentation has created a market for secondary manuals to supplement or replace the primary documentation published by software manufacturers. To discover the similarities and differences between the primary and secondary manuals, and to account for the popularity of the secondary texts, two best-selling books for a word processing and a spreadsheet program are compared to documentation supplied by the manufacturer. The .four texts were analyzed using using research and theory from cognitive psychology and rhetoric. The cognitive factors include processing of information in both short-and long-term memory, use of schema, and micro-and macroprocessing strategies used in text comprehension. The rhetorical factors are based on de Beaugrande and Dressler's notions of intertextuality, situationality, informativity, intentionality and acceptability. Analysis-shows that both the primary and secondary manuals support efficient

PAGE 4

text comprehension; however, strategies used in the secondary texts encourage long-term conceptual learning while strategies used in the primary texts tend to .support short-term recall and immediate use. The secondary texts also build a stronger relationship with the reader through closer identification with the reader's needs and through persuasive techniques. It is hypothesized that because the two levels of documentation evolve from different contexts, they identify with and serve different audiences. The form and content of this abstract are .approved. I recommend its publication.. S1gned Charles c. Beck iv

PAGE 5

Figures Tables CHAPTER CONTENTS vii viii 1. INTRODUCTION 1 The Demand for Computer Documentation 1 current Research in Computer Documentation 4 Methodology -Discourse Analysis 12 2. FACTORS FOR ANALYZING SOFTWARE DOCUMENTATION 19 Cognitive Factors Memory Models Levels of Processing Schema Theory Text Processing Theory Rhetorical Factors Intertextuality Situationality Informativity 20 20 22 31 38 44 45 53 54 Intentionality and Acceptability 58 3. ANALYSIS OF THE DOCUMENTATION 66 Cognitive Factors 66 Depth of Processing 67 Invoking Prior Knowledge 70

PAGE 6

Building New Schemas Facilitating Text Processing Rhetorical Factors Intertextuality Situationality 74 76 80 80 85 Informativity 87 Intentionality and Acceptability 91 4. DISCUSSION OF SIMILARITIES AND DIFFERENCES 103 APPENDIX A. SAMPLES OF FOUR TEXTS B. TEXTS USED FOR ANALYZING COHERENCE C. TEXTS USED FOR ANALYZING DENSITY .BIBLIOGRAPHY TEXTS USED FOR ANALYSIS vi 113 122 130 135 142

PAGE 7

FIGURES Figure 1.1. Levels of communication for software manuals 15 A.1a. First sample page from WordPerfect Workbook, reduced 80%. 114 A.1b. Second sample page from WordPerfect Workbook, reduced 80%. 115 A.2a. First sample page from Using WordPerfect, reduced 92%. 116 A.2b. Second sample page from Using WordPerfect, reduced 92%. 117 A.3a. First sample page from 1-2-3 Tutorial, reduced 85%. 118 A.3b. Second sample page from 1-2-3 Tutorial, reduced 85%. 119 A.4a. First sample page from The ABC's of 1-2-3, reduced 95%. 120 A.4b. Second sample page from The ABC's of 1-2-3, reduced 95%. 121 vii

PAGE 8

TABLES Table 3.1. Density of New Words in Each Text 88 3.2. Comprehensiveness as Measured in Text Pages and Index Columns 89 3.3. Analysis of Texts Using Gibson's style Machine 98 3.4. Comparison of Primary and Secondary Texts for Cognitive Factors 100 3.5. Comparison of Primary and Secondary Texts for Rhetorical Factors. 101 viii

PAGE 9

CHAPTER 1. INTRODUCTION The Demand for Computer Documentation The advent of computers and software for personal use has created an unprecedented need for educating nontechnical people about technical matters. Although computers been used for almost a half century, their earlier use was primarily in industry, science, engineering, and defense. The people who worked with them either had a high degree of formal technical education, as scientists, engineers, or computer programmers did, or received on-the-job training, as clerical workers or operators did. The more general user was concerned only with filling out forms to enter data correctly or being able to use the data put out by the computer, often in the form of a report or a control document such as a requisition slip or invoice. Personal computers (PCs), introduced in the early 1980s, not only broadened the user base to include nontechnical professional people, such as lawyers, teachers, writers, and business executives, but they also introduced software that is both flexible and complex.

PAGE 10

Professional and clerical workers alike acquired a powerful tool for creating, manipulating, and saving written text, spreadsheets, and databases of information. Unlike previous machines, automobiles fbr instance, which extended people's physical capabilities, these were intellectual tools, which extended our minds and seemed accessible only to the privileged few who already understood them. Non-technical people needed user's guides--and writers of user's guides--that could make this new technology intelligible to them. As a consequence of this need, endless. shelves of computer documentation, instruction manuals, and operating guides have been published. Every manufacturer of PCs and every developer of PC software has accompanied its product with some kind of text explaining how to use the hardware, operating system, utility, word processor or application software. For discussion purposes, I'll refer to the documentation from the manufacturer as the primary text. Supposedly these.texts, especially software documentation, have been "inadequate, arcane, and confusing" (Anthony 1989). To capitalize on consumer demand for better--or different--information about the same hardware and software, book publishers have created a new category of books and are selling them through traditional bookstores, software retailers, and even grocery stores. These secondary texts are generally 2

PAGE 11

perceived to be more helpful than the primary ones {Anthony 1989; Wells 1989). At the very least, we know that people are buying these books, and they're choosing them not on the basis of advertising but through favorable reviews in computer magazines and, more importantly, through word of mouth {Anthony 1989). It's also possible that some users buy a software book because they pirated a copy of the software and, thus, have no access to the original documentation. The size of this market, however, would be difficult to measure. In any case, some software books still outsell others on the same.subject. The existence of these two types of texts, with their perceived difference in quality, affords a tempting opportunity for research. What similarities or differences can we identify that would account for one being "better" than the other? What principles can we derive that writers of documentation could use to improve future texts? Should the authors of primary texts be doing anything differently? Before discussing this possibility for research further, let's look at other research used in writing computer documentation and user's guides. 3

PAGE 12

current Research in Computer Documentation At present writers and designers of software documentation have at least four sources of information to guide their creation of effective material. The first source is empirical research that determines how subjects read and how well they learn from various kinds of texts. The second is a less formal approach called usability or product testing, a process which is akin to product testing in manufacturing. A third source is the empirical research of cognitive psychology, the scientific inquiry into how people process information, often based on the computer model of processing information. Finally there is the experience of documentation writers who offer their knowledge in how-to books on writing software manuals. A typical report in the area of research on learning, instruction, and reading is Mayer's (1982) discussion involving five variables for "increasing the novice's understanding of scientific or technical prose" (445). Mayer emphasizes helping students understand, that is, helping them acq\J.ire meaningful knowledge that they can apply by solving problems in new situations. It's the kind of knowledge that enables software users to go beyond memorizing commands in a program to combine commands for a new effect, such as creating hanging 4

PAGE 13

indents when using a word processor. Mayer synthesizes the results of many researchers including himself, to show the advantages of 11(1) ordering prose to start from familiar concrete concepts and go to abstract formulas, (2) using advanced organizers, (3) providing training in prerequisite knowledge, (4) encouraging use of elaboration strategies, and (5) inserting meaningful adjunct questions within the passage" (445). He evaluated the effectiveness of each variable by measuring subjects' achievement on recall, .retention, and problem solving tasks. Using a methodology very similar to that used for traditional educational materials, researchers are beginning to analyze the effectiveness of software documentation in particular. Doheny-Farina (1988) presents several such studies in Effective Documentation: What We Have Learned from the Research. Charney, Reder, and Wells (1988) experimented to find under what circumstances users would prefer lengthy natural language rather than very brief or minimal information. On the other hand, Carroll, Smith-Kerker, Ford, and Mazur-Rimetz (1988) show that subjects using a minimal manual are more efficient, particularly in getting started, coordinating attention between the manual and the screen, recovering from errors, and using the manual for reference. In a related study, subjects who used a set of brief "guided 5

PAGE 14

exploration" cards learned more than subjects who used a self-study manual (Carroll, Mack, Lewis, Grischkowsky, and Robertson 1988). For the most part, these studies were conducted with from 12 to 80 subjects. Rubens and Rubens (1988) conducted two "usability" studies in which subjects worked with the software documentation without interacting with the program. The subjects examined one of two manuals and then answered questions, stating both the answer and its location in the manual. In both studies researchers manipulated the manual's format and found, surprisingly, that design changes based on "formatting techniques purported by the research to increase a manual's usability" (229) actually made the manual harder to use. Another method for researching. effectiveness is usability testing (Doheny-Farina 1988; Gillihan and Herrin 1988; Gould 1988). Usability testing can be carried out both before and after publication of the finished documentation. Using a pre-publication draft, researchers can observe how computer users interact with the documentation and then revise the draft depending on the results of the test. Sometimes the test is conducted by observing and recording the users' actions or by having the user think aloud and recording this protocol either manually or on audiotape (Flower, Hayes, and Swarts 1983). Another approach is to have the users talk 6

PAGE 15

about their experiences after they've finished using the manual. Even after the manual has been released, information about its effecti venes.s can be gathered by using questionnaires and surveys, by noting the types of problems mentioned on the customer helpline, and by visiting the customer site to see how the manual is used (Gillihan and Herrin 1988). During usability tests conducted by Ramey (1988) for software manufacturers such as Microsoft and Aldus, users revealed their preferences for information that's oriented toward their work, strategies for effective use of software commands, warnings about possible problems, a layered presentation of beginning and advanced concepts, varied types of indexes and tables of contents, and page formatting that aids comprehension. A third kind of research from which we derive useful document design principles involves experiments in cognitive psychology, experiments that aim to uncover the way people process verbal and visual information. Much of this research has been summarized with guidelines added to make the information more practical (Felker 1980; Duin 1989). A 1986 report from the Communication Design Center of Carnegie Mellon University reviews relevant literature for designing computer documentation. Lewis's discussion of "Design Principles for Pictorial Information" (1988) is based on studies of how people 7

PAGE 16

process visual information, including individual differences in processing. From this research she offers guidelines for graphics in computer documentation: pictorial representations of equipment and systems, typographic cues for orienting readers to the manual itself, and diagrams for processes and procedures. For technical writing in general, Huckin (1983) takes, as his title suggests, a cognitive approach to readability, offering eight guidelines for creating text that's efficient for the reader. Huckin suggests that "more research needs to be carried.out with actual technical writers and readers performing typical technical tasks" ( 101) 0 A fourth source of advice comes from experienced writers of software manuals. This advice usually takes the form of how-to books covering the-entire process, such as Houghton-Alico's Creating Computer Software User Guides (1985) and Price's How to Write a Computer Manual: A Handbook of Software Documentation (1984). Frequently articles in Technical Communication address specific portions of the process, as Major (1989) does in his article on choosing the right form of documentation. Major draws from his own experience both as writer and director of computer operations to explain the differences between user guides, tutorials, reference manuals, and standard operating procedures and how each 8

PAGE 17

can suit a given situation. While Major doesn't discuss his categories in terms of rhetorical analysis, he is actually addressing the rhetorical concern of genre: what distinguishes categories of texts and why. This area of research, based on rhetoric or discourse analysis of texts, seems lacking for software documentation. Using a computer-aided search, I found only one relevant abstract out of the entire database for "Language" in Dialog. Key used for the search were "text analysis or linguistic analysis or rhetorical analysis" and "software documentation or computer documentation." The relevant citation was for an article by Mirel (1988) in which she derives writing principles from cognitive psychology and text linguistics and then illustrates how the principles have or have not been applied in Microsoft's Word manual. Specifically she analyzes principles that can guide writers in making choices within three functions of language as defined by Halliday: the ideational, textual, and interpersonal. The ideational concerns how readers process conceptual information and how that process affects the choices writers make for presenting background i'nformation; for offering problem solving strategies; and for using active versus passive voice, affirmatives versus negatives, and verbs that imply associated cases. The textual function 9

PAGE 18

deals with organizing and formatting texts; choosing cohesive ties, especially using "the" to indicate external reality or shared knowledge; and choosing among synonyms, pronouns, and repetition for reference to a single concept. The interpersonal function concerns the invoked relationship between writer and reader. In computer manuals that relationship depends on the reader's attitude toward computers and his job and on the writers' choice of voice, mood, and modal auxiliaries of verbs. These functions of and the principles derived from them are useful for analyzing texts, but they need to be applied more thoroughly if we are to compare one whole text to another. By browsing I've found a few other articles that apply rhetorical analysis to technical communication. These range from applying rhetorical theory broadly to applying just one aspect of rhetoric to sof.tware documentation in particular. One broad treatment is Harris's "Theoretical Perspective on 'How To' Discourse" (1983) which explains the role of semantics, syntactics, and pragmatics in how-to texts. Ramsey (1980) used a survey method to explore grammatical voice and person in technical writing. on figures of speech include Halloran and Bradford's (1982) discussion of figures in the "Rhetoric of Science and Technology" and Kallendorf and Kallendorf's (1985) discussion of "Figures of Speech, 10

PAGE 19

Ethos, and Aristotle" in business communication. More specific to my investigation is Bradford's (1984) commentary on "The Use of Persona in Microcomputer Documentation." Despite the lack of previous work in which techniques of text linguistics and rhetorical theory are used to analyze software manuals, the approach still seems useful for helping technical writers understand how characteristics of their texts can affect the text's usefulness. Five shared assumptions of rhetoric and text linguistics, as defined by de Beaugrande and Dressler (1981), point the way to this approach: (a) the accessing and arranging of ideas is open to systematic control; (b) the transition between ideas and expressions can be subjected to conscious training; (c) among the various texts which express a given configuration of ideas, some are of higherquality than others; (d) judgements of texts can be made in terms of their effects upon the audience of receivers; (e) texts are vehicles of purposeful interaction (1981, 15). In particular, statements c, d, and e suggest that we can discover why the primary and secondary documentation, which treat the same subject, differ in their reception and perhaps usefulness. 11

PAGE 20

Methodology -Discourse Analysis In this study I use theory and research from cognitive psychology and rhetoric to analyze two sets of software manuals. The first set is the documentation supplied by the manufacturers for WordPerfect 5 and Lotus 1-2-3. The other set includes best selling handbooks published by Que and Sybex. Instead of a direct, laboratory measurement of how effectively a student learns from a text, the market for secondary software manuals provides an indirect measurement of a text's effectiveness. I am assuming there is a positive correlation between the number of books sold and the usefulness of that book to readers. Granted, other factors contribute to the book's volume of sales: the amount of publicity and advertising paid for by the publisher; the persistence of the publisher's sales staff, the distribution channel. In general, however, demand will decline if readers do not find the publisher's promises fulfilled. This would be true both for a single text and for multiple titles from the same publisher. One of the secondary texts I've selected, Using WordPerfect 5 from Que, is not only the best selling of all software books, but its publisher is the leader in software books (Anthony 1989). The other secondary text, The ABC's of 1-2-3 from Sybex, is the 12

PAGE 21

second best selling book on Lotus 1-2-3. I've chosen not to analyze the top selling book, which is published by Que, because the Sybex book offers the opportunity to compare another publisher's text with the manufacturer's documentation. The fact that so many books are sold for WordPerfect and Lotus 1-2-3 may reflect either the difficulty of the original documentation or the popularity of the software. WordPerfect 5 is the best selling word processing software for IBM and compatible PCs, with 2,135,000 copies sold between its release in May 1988 and December 1989 (Tanner 1989). And Lotus 1-2-3 has dominated the spreadsheet market since 1983 (LeBlond and Cobb 1985). Coincidentally, of the fifteen best selling computer books, according to Waldenbooks (Anthony 1989, 30), six of them, 40%, pertain to WordPerfect 5 and two pertain to Lotus 1-2-3. Using market success to judge how well software users learn from the text may have a greater degree of reliability than market success in the school textbook business. School texts are selected by individual teachers, committees of teachers, and committees of parents and teachers. They professionally evaluate whether or not a text is suitable for learning. The software manuals, however, are bought by the students themselves, adult learners who are highly motivated to 13

PAGE 22

learn the material as efficiently as possible. They are likely to choose a book most compatible with their needs. By examining textual similarities and differences among the primary documentation from the manufacturer and the secondary texts from publishers, I hoped to discover characteristics in their design that might account for the popular acceptance of the Que books and the purported rejection of the. manufacturer's documentation. These characteristics would then warrant further investigation. If they were found to be consistently different in a broader sample of documentation and software books, we could draw up a set of guidelines based on what seems to be working in the marketplace. These guidelines could serve writers of both primary and secondary texts. We could also test the characteristics, particularly the rhetorical ones, in a laboratory to determine how or why a characteristic enhances or detracts from usability. What I expected to find, is not that the two texts differ so much because one is more useful or of better quality than the other, but that they serve different discourse communities and that neither text could satisfy those communities without the other. I suspect that the two work together much like a system of canal locks that enable boats to travel between bodies of water that are at different levels (figure 1). 14

PAGE 23

Programners and System Designers Manufacturer's In-house Writers Knowledgeable Users/ Technical Writers Knowledgeable Users/ Trainers -----------------------1 -----------t---------1 Program; System Specifications Primary Documentation Secondary Documentation Quick Training Manual Figure 1.1. Levels of communication for software manuals The manufacturer's documentation takes information from one level of understanding, that of the programmers and system designers to another level, that of knowledgeable users and perhaps other technical writers. These users are probably comfortable with a technical, logical, highly symbolic environment and willing to extract from the documentation what they need to learn the program. If the users are also professional writers, they can take the information to yet another level, that of general users who want instructions geared to their immediate needs and interests. In turn, someone who has mastered the software through either the primary or secondary documentation can create a short set of training instructions, perhaps a minimalist manual, geared to teaching just a restricted set of tasks. The process is extended further when general users make their 15

PAGE 24

own sets of notes, for example a set of symbols to remind them of the keystrokes needed for a carrying out a function. Ironically, these notes may resemble the quick reference cards provided by the manufacturer, but the end users could not have understood the cryptic reference cards unless they had already reached a certain level of understanding about how the program operates. The levels of information indicated in figure 1 represent many kinds of levels. The difference in level could be a difference in technical knowledge about computers, software, or word processors. It could also be a difference in comfort level (experience), level of abstraction, or level of detail. A user who is at a high level in one respect may not need to be at a high level in other respects. For example, a user who is at high level of knowledge about computers may not need a high level of background information when learning a new word processing program. Just as we can represent users as being at different levels of understanding, we can also represent them as being part of narrow or broad discourse communities, with reference to the software. The originators and developers of a software program share a very specialized knowledge and thus belong to a small community. The inhouse writers who work with the developers share some of that knowledge, but they also participate in a larger 16

PAGE 25

community of users who have less technical knowledge. The publishers and writers of software books may have ties with the developers, but their allegiance is to a broad public with very little specialized, technical knowledge. This public is less interested in the fascinating features of the software and more anxious to see how the software helps them do their job better. This model represents the dissemination of knowledge as a ripple effect. Viewed from this perspective, each level of software documentation reaches a wider user group. To assess how the texts facilitate learning, I first summarize theory and research from cognitive psychology that explain how humans process and store information, how we represent meaning in memory, and how we process written text for comprehension and retention. I then examine factors in rhetoric and text linguistics that influence how readers use a text. I look at how documentation reflects the traditional elements of a rhetorical situation--writer, reader, and content--and a fourth element, purpose, from discourse analysis. Specifically, I want to discover what persona and tone are projected by the writer, what role the reader is supposed to play, and what the "invoked relationship" (Mirel 1988) is between the two. Under content, I examine the selection and arrangement of information. In general I follow the the text linguistic framework 17

PAGE 26

provided by de Beaugrande and Dressler (1981), concentrating on five of the "basic notions:" intertextuality, situationality, informativity, intentionality, and acceptability. The results of my analysis are more qualitative than quantitative, but they are based on direct observation of the two sets of texts. I have made every attempt to cite examples from the books and to explain the reasoning I used to reach my conclusions. 18

PAGE 27

CHAPTER 2 FACTORS FOR ANALYZING SOFTWARE DOCUMENTATION Several academic disciplines contribute to our production and understanding of instructional text: cognitive research and theory, rhetorical theory, and instructional technology. In this section I discuss factors from each of these disciplines that I'll use to analyze examples of software documentation. While some researchers (Felker 1980; Mirel 1988; Duin 1989) used these disciplines to derive principles and guidelines for writing documentation, I prefer to consider "factors" since these are often only theory and the research yields conflicting results. With few exceptions all of the works cited here pertain to empirical research or theories that have been the basis of research. I chose not to use material that was derived solely from the practical experience of technical writers. In the following sections I discuss the factors in three groups: cognitive, rhetorical, and format. However, the division is somewhat arbitrary since factors from each group are interdependent. For example, the format of a text can influence cognitive processing, and

PAGE 28

techniques that improve cognitive processing can enhance the rhetorical relationship between writer and reader. Cognitive Factors From research and theory ori human information processing and human memory, we can identify several factors affecting how we construct text so that it is easier for readers to comprehend and recall. Memory Models Building on the work of Herman Ebbinghaus and the speculations of William James in the 19th century, cognitive scientists in the 1960s found new inspiration from computer science and artificial intelligence. They constructed models that represented information processing and memory as a series of separate stages or, in analogy to computers, separate processors (Norman 1976; Solso 1988). The first stage consists of attending to physical stimuli (sight, sound) and deciding whether to admit the stimuli to the second stage, short-term memory. The attention stage lasts for mere fractions of a second, and, if stimuli are not selected for transfer to short-term memory, they are immediately forgotten. The meaning of the stimuli is generally not considered. In short-term memory, however, stimuli are analyzed for meaningful content and used for momentary purposes, 20

PAGE 29

such as dialing a telephone number, deciding what to order in a restaurant, or, in the context of software documentation, looking up a command sequence and executing it. Short-term memory is characterized by short duration, varying according to researcher from just seconds to maybe 20 -minutes. It also seems limited in capacity, generally assumed to allow seven, plus or minus two items, to be held simultaneously (Miller, cited in Norman 1976, 89-95). It undergoes semantic processing as we try to give meaning to the items. However, it's possible to hold information in short-term memory by just repeating sounds--the phonemic part of words or numbers-or possibly just shapes in the case of purely visual stimuli. If we want to remember an item for longer than a few minutes, we have to transfer the information to a third processor, long-term memory. How the information is transferred becomes a critical issue. In the multi-stage model, the transfer is usually accomplished through the process of rehearsing, repeating over and over the information in short-term memory until it becomes relatively permanent in long-term memory. Long-term memory seems virtually unlimited in capacity and duration. 21

PAGE 30

Levels of Processing Because there is no satisfactory explanation of how rehearsing actually aids the later recall of information,. and because the stage models sometimes have fuzzy boundaries for duration and capacity, craik and Lockhart (1972) offer an alternative framework. After reviewing research on memory, they suggest that previous findings could be explained by a single processor model for memory. How long we retain information depends not upon the features of a memory unit, e.g., the short duration and limited capacity of short-term memory, but on the levels of processing. How we process the information determines whether we deal with only a few items at a time and then forget them quickly or whether we retain larger chunks for a longer time. In their view, the more meaning we attach to the information, the more information we can store tor a longer period. Greater depth of processing is equated with a greater "degree of semantic or cognitive analysis" and "enrichment or elaboration" (Craik and Lockhart 1972, 675) of words, sights, smells, and touch. The deeper we process the information, the more associations we make, the longer and stronger memory trace. Maintenance versus Elaborative Processing. The amount of time we spend processing information is not directly correlated with the length of time we retain 22

PAGE 31

information. If we maintain information at one level of processing (Type I processing or "maintenance rehearsal"), that is, if we rehearse it or continue to hold it in consciousness, we will not necessarily improve our long-term memory for it, no matter how long we process at that level (Craik and Watkins 1973, cited in Norman 1976, 119). However, if we subject the information to deeper analysis (Type II processing or "elaborative operations"), we will be able to remember it longer. And the more time we spend analyzing at a deeper level, the better the memory will become. on the other hand, if we are already familiar with the information, we can process it both deeply and quickly. Type I processing can be called "data-driven," that is, the processor is simply loqking at units of information and not finding any particular way to process them, other than repetition. When readers do begin to see a way to organize the items or do discover a pattern to fit them into, they begin to process the items at a deeper level. (Terminology can become confusing here, because data-driven approach is also called bottom-up processing, where we begin by analyzing something at a "low level" and through successive analysis, bring it to a higher level of understanding, but the analysis itself is a "deeper" kind of analysis.) Type II processing is conceptually driven. We begin with some idea of how the 23

PAGE 32

individual elements are related--a pattern or framework or schema, and then process the items by relating them to the concept (Norman 1976, 40-41). Research in neurology supports the idea that maintenance rehearsal is not effective for long-term storage. In discussing the pitfalls of short-term storage (defined as lasting from a quarter of a second up to eight hours), Hand (1982) cites O'Keefe and Nadel's conclusion: "The results of two studies strongly indicate that verbal information in short-term memory is stored in a 'discrete neural area (the posterior parietal region) and not a part ofany causal short-term memory to longterm memory chain"' (94). Neurobiologists further believe that long-term memory consists of two types of storage: the taxon system and the locale system (Hand 1982). The taxon system seems to contain information that was transferred to long-term memory using the rehearsal strategy. It is rote, verbatim, and categorical: it is not contextual or time referenced. The locale system, by contrast, is highly contextual and may contain many associations involving all the senses, based on episodic memory as well as semantic memory. For example, if we want to find out how many days are in June, we can access the taxon system and recite a rhyme. But if that is our only method for 24

PAGE 33

knowing the number, we have to recite the rhyme until we come to the month (or don't come to it, as in the case of July). We can't access the.month randomly, only in sequence. If, however, our birthday falls on June 30th, then we may have developed many associations with that date, including the fact that it's the last day of the month. If we build up similar associations for the last date of every month, then we can probably access those dates, too, without reciting the rhyme. Both Type I and Type II as well as the taxon and locale systems, have implications for software documentation. At times writers may want to encourage Type I processing, with its mere repetition of items, by listing a short sequence of commands to carry out. Bjork and Jongward (cited in Norman 1976) found that Type I processing had a slight edge over Type II processing when immediate recall (20-second retention) was But for recall later (same day) Type II or elaborative processes were better. "Bjork concluded that maintenance rehearsal is better as an operation for temporarily holding information following its presentation, but is clearly inferior to elaborative processes in terms of facilitating long-term performance" (119). In.the same manner, documentation writers might want to encourage verbatim memory in the taxon system, especially when cryptic commands, such as use of the functions keys, seem 25

PAGE 34

arbitrary and may simply have to be memorized without a meaningful association or with only idiosyncratic associations. Mayer (1982) reaches similar conclusions in a summary of research on instructional variables in text processing. Mayer finds that some instructional techniques are better for promoting meaningful learning, that is, transfer of learning to new situations and problem solving; while others are useful for immediate recall and verbatim memory. Since all of the experiments cited involved processing of technical or scientific information by novices, his analysis is particularly relevant to software documentation. According to Mayer, the following techniques encourage meaningful, long-term learning; while varying the technique or not using it, encourages factual, learning. organizing the text from familiar-to-formula. That is, providing conceptual information before specific formulas or details: how a camera works before a description of its parts. Presenting conceptual information at the beginning encouraged creative problem solving. In several experiments, this approach led to better overall performance for students lacking a strong background in mathematics and science. Presenting the formula first encouraged only memory of facts. 26

PAGE 35

Providing concrete advance organizers. That is, using models or analogies; for example, comparing file management in a computer to traditional file cabinets and in-out baskets. If the analogy was presented before the to-be-learned information, subjects excelled in remembering conceptual idea units and creative problem solving. If no model was presented or if the model was presented after the to-be-learned information, subjects performed better on immediate problems and at retaining technical facts. "Advance organizers tend to have their strongest effects when the material is unfamiliar--so that the learner does not already possess his/her own model--or when the subject is a novice and when the dependent measure is creative problem solving" (Mayer 1982, 454). Elaboration strategies. These include use of notetaking such as summary writing, paraphrasing, or a written exercise involving comparison. Note takers were better at recalling conceptual information and making inferences. Non-note takers were better at recalling technical facts. Mayer also reports strategies that emphasize repeating information, either echoing words present on audio tape or simply rereading a passage. These strategies only reinforce learning for individual facts and verbatim recognition, not for conceptual ideas or problem solving. 27

PAGE 36

Too much elaboration, as well as too little, may hinder recall. Studies by Mandl and Ballstaedt (1982) show that if subjects, who were encouraged to elaborate on their own through read-aloud protocois, elaborated too much, they actually recalled less. Also subjects who used elaboration without a task orientation were less effective at recall than those who had a task orientation or who didn't elaborate at all. Pretraininq in prerequisite knowledge. Giving background information before reading a passage; for example, presenting the underlying concepts of "trial" and "outcome" before a text on probability theory. The results of these experiments suggest that background information is helpful only when the instruction is geared toward remembering concepts rather than formulas. Using inserted questions. That is, presenting questions in the text, either before or after the to-belearned material, will act as a signal to the student about what to remember. Unless we want readers to focus on only a few specific areas, the questions must be balanced for content. Differences in learning for immediate recall and verbatim memory as opposed meaningful conceptual memory may also account for the success Carroll, Smith Kerker, et al. (1988) had with the minimal manual. The minimal manual eliminates many aids for increasing depth 28

PAGE 37

of processing--previews, reviews, practice exercises, index, and the "welcome to word processing" introduction. It focuses on specific tasks to be accomplished. Two empirical laboratory studies were used to test its efficiency for learning. In the first study, which simulated an office environment, the group using the minimal manual took less time to learn and had greater performance success than the control group using a commercially available, self-instruction manual. The second study used a 2x2 design in which the variables were the two manuals and two learning strategies, learning-while-doing and learning-by-the-book. For both learning strategies, the subjects using the minimal manual were more efficient, particularly in getting started, coordinating attention between the manual and the screen, recovering from errors, and using the manual for reference. In three studies that challenge the results reported by Carroll, Smith-Kerker, et al. (1988), Charney, Reder, and Wells (1988) questioned whether lack of elaboration really was effective. Their first study compared subjects using four kinds of texts for learning how to use a PC operating system: an elaborated manual with or without task orientation and an unelaborated manual with or without task orientation. Subjects who used the unelaborated manual without task orientation 29

PAGE 38

"consistently performed poorly," while subjects with the elaborated, non-task oriented manual were slightly more efficient than subjects using either manual with task orientation. The second study tested which kinds of elaboration were more helpful--elaboration of concepts or elaboration of procedures. Charney, Reder, and Wells found that for both novice and expert computer users rich procedural information increased subjects efficiency. Elaborated conceptual information without rich procedural was not effective. Finally, they compared four learning strategies: reading a brief spreadsheet manual by itself, reading with three tutorial problems (controlled examples), reading with three exercises but no tutorial, and reading with a tutorial problem and two exercises. The subjects who were most efficient at performing tasks were those who read the tutorial plus exercise version. Preliminary results of another study challenge the conclusions concerning benefits of discovery learning (also encouraged by the minimal manual). "Exercises that set specific goals" support learning better than discovery alone {Charney, Reder, and Wells 1988, 61). Further support for including elaborative material comes from a study reported by Shriver et al. {1986). Researchers found that documentation which combines 30

PAGE 39

global and detail information yield better performance, measured by time-on-task, than either global or detail information by itself (102). In summary, research on memory and the levels of processing theory and point to different strategies for different learningpurposes. To encourage conceptual learning and problem solving, documentation writers can provide background information, advance organizers such as analogies and models, and elaboration strategies such as exercises and questions. To encourage memory for facts and immediate recall, writers should present the information "straight" with little elaboration. In either case, providing a specific task to accomplish will increase readers' performance. Schema Theory If strategies for indreasing the depth of processing work, it is probably because some of them activate existing mental representations of meaning, usually referred to as schemas. Earlier in this century Piaget suggested the concept of scheme for "a mental representation of some action that can be performed on an object" (Solso 1988, 352). He theorized that all learning takes place through a dual process of assimilation and accommodation and that learners try to fit new knowledge into existing schemes. More recently, 31

PAGE 40

cognitive psychologists have adopted the term schema in their models of how we represent meaning in memory. our mental structures of meaning are built upon word associations (e.g., trees, bushes, flowers) and hierarchical networks of those words (e.g., trees, limbs, leaves). Research (Norman Solso 1988) shows that we not only remember items better if we are presented them in an hierarchical arrangement, but that if they aren't in an hierarchy, we attempt to put them in one so we can remember the items. Discourse analysis is primarily concerned with semantic memory, but schemas apply to other kinds of memory as well, such as chess movements, dance steps, or strokes at a keyboard, which may be stored as visual, auditory, or kinetic schemas (Norman 1976, Solso 1988). Building non-semantic schemas may be equally important in teaching people to use computers. Memory for keystrokes could be stored as semantic information ("Hold down Shift while pressing Enter") or as kinetic information (a feeling of using the left pinkie and the right index finger together) In the case of kinetic memory, practice (or rehearsal) may become more important than depth of association to increase long-term memory. Schemas build in ever more complex levels, from representations of objects, .events, and abstract concepts to representations of a series of actions, known as 32

PAGE 41

scripts. Scripts are the organized bits of stereotyped information people form about common situations. Scripts for an activity such as "going skiing," encompass many sub-scripts: gathering all the gear (schemas: boots, poles, skis, gloves), driving to the mountains, parking, buying a lift ticket, standing in line, etc. When we talk about "going skiing", we activate all of.these subscripts and schemas. Schemas and scripts serve three important purposes for writers of instruction manuals: (1) existing schemas can be invoked to provide the reader with a framework for assimilating and accommodating new knowledge (Jonassen 1982, 7-8: Huckin 1983): (2) new schemas must be built or old ones reorganized (Norman 1976, 73) in the reader's mind for new information to be remembered, and (3) schemas for text organization serve as an aid for processing text (Kintsch and Van Dijk 1978). Invoking existing schemas. The primary function of advanced organizers--analogies and models (as defined by Mayer 1982)--is to invoke schemas, giving readers a way of tying new 'information to old. Analogies, however, have drawbacks. They can confuse novice readers who are unable to see the exact correspondences between elements or who may get stuck on a concrete level without understanding the abstract concept or principle being explained. Analogies take extra time to read and 33

PAGE 42

understand, and they may not be needed by some readers. Care also has to be taken that elements of the old (1) are known to the reader and (2) that_they match up properly with the new (Rumelhart and Norman 1981; Mayer 1982; Curtis and Reigeluth, cited by Shriver et al. 1986). While most research supports the effectiveness of using analogies for increasing learning (Rumelhart and Norman 1981; Mayer 1982; Simons 1982), their efficiency has been questioned. They generally require more time for reading and they seem to have a stronger effect on subjects characterized as visualizers rather than on verbalizers. Simons concluded that It does not make sense to make special books with analogies for visualizers and others without them for verbalizers. The data-base for such .a simplifications is still too weak. Furthermore, it is not as yet possible to measure these individual differences in a practical setting. Instead, more concrete analogies should be included in textbooks than is done thus far, but these analogies should be place in such a way that subjects are free to either use them or not (470). Theimportance of invoking or activating a schema is illustrated in a now famous study by Bransford and Johnson (1972, cited in Duin 1989). They asked subjects to read a short passage describing a process. Readers who did not have the title of the passage, which named the process, had a hard time remembering the content of the passage. Readers who had the title 11Washing Clothes11 were able to remember much more of the content. Readers 34

PAGE 43

without the title lacked a schema for relating the incoming information. Thus titles are one means of activating the appropriate context for processing new information (Kozminsky 1977; Bock 1980). Building New Schemas. Schemas can be like algebraic formulas, where we have a concept of something that can be filled in with particulars. For example, we have a formula for describing what players do in a football game: X does Y. it's the same formula for what people do in general, but if we activate the schema for football, then we can fill in the slots with more specific terms: Elway passes the ball, Johnson runs the ball, Jones blocks the receiver. Interestingly enough this schema matches the scheme of Piaget, mentioned earlier, and it follows the pattern of case grammar, sometimes called role relational grammar, laid out by Fillmore (1968). English sentences are based on a central action, event, or state described by a predicate and explained by its "arguments," including a subject as agent. The "who does what" schema is also the basis for the scenario principle discovered by Flower, Hayes and Swarts (1983). They derived the scenario principle by analyzing read-aloud protocols taken while people tried to read government instructions and make sense of them. The protocols further substantiate the theory that we rely on 35

PAGE 44

schemas and scripts for processing and storing information. Flower, Hayes and Swarts found that readers would 11restructure11 the bureaucratic language into active voice statements that stated exactly what the reader was to do. The researchers recommend that writers state regulations and instructions using agents and actions (who does what) since that is the scenario (script) that readers construct for themselves. The scenario principle is thus a means of helping.readers build their own new scripts. Carried over to software documentation, the scenario principle suggests that writers should organize instructions for using the computer according to tasks that the user usually performs. To do this, writers must take advantage of the reader's work schemas to build a new schema for using the computer as a tool. Ideally the programs themselves should be written around a scenario principle: what does the user want to accomplish on the job? Ramey (1988) and Gibson (in Shriver et al. 1986, 87) arrived at the same conclusion when analyzing how users actually work with manuals and what their preferences are. In an experiment at the sentence level, Dixon found that subjects prefer to have the action stated first, e.g., 11Press C if you want to continue," rather than the 36

PAGE 45

condition first. "The results also suggest that a person's internal plan is organized as a list of actions" (Shriver et al. 1986, 90). According to Rumelhart and Norman (1981), building new schemas for procedural knowledge is "enormously more difficult" (337) than adding new declarative (factual) knowledge. This is true, in part, because procedural knowledge is not as readily accessible as data. We "know how" to do something, e.g., tie a shoe lace or hit a baseball, without being able to "explain how" we do it. They suggest that analogies which activate existing procedural schemas, can play a critical role in building new knowledge. However, since readers' mental models will vary, writers need to supply readers with "analogical frameworks more appropriate than the ones [students] naturally used" {356). Through an experiment based on learning a text editor, Rumelhart and Norman discovered that if readers are to transfer the right features from the original analogy or model to the new model, they need many simple models, "each making a different point" {356). Kieras and Bovair (in Shriver et al. 1986, 13) found that subjects who first learned from a model performed procedures 20% faster and remembered more than subjects who learned without the model. Using Schemas to Process Text. In addition to being important for relating new information to old and 37

PAGE 46

for building new representations in memory, schemas can cue readers about how to process a text. Kintsch and Van Dijk (1978) believe we have schemas that represent our knowledge of text structure for different genres such as reports, stories and novels, biographies, text books, or cook books. Readers, especially competent ones, use their knowledge of the text structure to decide what's important to process and remember while they're reading. They can then make decisions about the "macro level" of individual propositions. In addition, readers have expectancies about how a text will progress. A familiarity with a given text structure, such as scientific reports, makes it easier for readers to predict and comprehend what's coming next as they read. By understanding how readers process written text and remember it, software documenters can better help readers use the text. Text Processing Theory The Kintsch and Van Dijk (1978) model for text processing synthesizes many cognitive principles concerning hierarchical structures in memory, schemas, levels of process, and leading edge strategy. The model is based on parallel processing (see also Rihs-Middel 1982), concerned simultaneously with microprocessing of text (bottom-up, data-driven processing) and 38

PAGE 47

macroprocessing of text.(top-down, concept driven). At the micro level, readers are reading in a linear fashion, processing one proposition and then another. (A proposition has been defined as the smallest unit of assertion; it's useful for quantifying the units of information that readers have to process and may later recall.) Short-term memory (or Type I processing) is limited in the number of propositions that can be held at one time, so the model presents a strategy for deciding what needs to be processed further (following Craik and Lockhart 1972) and transferred to long-term memory. According to the Kintsch and Van Dijk model, readers store as many propositions as possible in short-term memory. Kintsch and Van Dijk posited four propositions, a number which yields the predicted results; ten does not. The number could be more than four, perhaps Miller's magical 7 plus or minus 2. The number of propositions could vary depending on the readers' familiarity with the material or the surface (syntactical) complexity of the propositions. The strategy for processing propositions determines what gets transferred to long-term memory. As craik and Lockhart (1972) proposed, the more processing a proposition receives, the more likely it is to be remembered. Kintsch and Van Dijk suggest two principles that guide the processing and selection of propositions. 39

PAGE 48

(1) Referential coherence. When words in the incoming proposition match the ones already stored in short-term memory, then the incomimg proposition is likely to be admitted to short-term memory and the related proposition to be reinforced and transferred to long-term memory. (2) Leading edge. Readers store and hold the proposition that comes in first, based roughly on sentence boundaries. If the incoming proposition has no terms in common with the proposition in short-term memory, then readers must spend a little more time processing it. They can can use their existing knowledge to make an inference, that is, to draw a logical connection between the propoitions; or they can search long-term memory or the preceding text for a proposition that's related. Both of these processes are "resource consuming"; they take time and may interfere with short-term processing. since poor readers usually take longer to scan short-term memory and match propositions, it's important to increase coherence and use more signaling devices to help them (Kintsch and Van Dijk 1978, 371; Pace 1982). Readers repeat this process to build up a representation of how the propositions are related. At the same time, readers use existing knowledge about the topic and its global organization (schemas; top-down, 40

PAGE 49

concept-driven processing) to make inferences and to guide choices about what in the text is important. They decide which propositions are connected to the topic of discourse, and they use "macro rules" applied recursively to delete some propositions, generalize about others (substituting one proposition for several), or construct new global propositions. The Kintsch and Van Dijk model yields important considerations for writers in general and software documenters in particular. (1) Techniques that contribute to coherence-repetition of key terms, pro-forms, paraphrasing, upholding the givenjnew contract (Haviland and Clark 1974: Irwin 1980; de Beaugrande and Dressler 1981; Goodin and Perkins 1982: Bamberg 1983)--help readers process at the micro level. (2) Techniques that keep topic of discourse focused in the mind of reader--titles and subtitles, paragraphs with topic sentences, sentence subject as topic (Kozminsky 1977: Bock 1980; Faigley and Witte 1983)--help the reader process at the macro level. (3) A predictable or explicit text structure provides a controlling schema (Kintsch and Van Dijk 1978, 389) for macroprocessing to work. (4) Following the Kintsch and Van Dijk model, other researchers have suggested that readers also use 41

PAGE 50

"motives, goals, or schemata of reader" to control comprehension (Jonassen 1982, 9-10; Rihs-Middel 1982). In a related experiment, Kintsch and Van Dijk (1978) used a shorter text and found that micro-and macropropositions were treated alike, that is, one did not seem more important than another. This was "unlike the situation where subjects read a long text and engage in schema-controlled macro operations!" (389). The subjects' responses were more reproductive, merely repeating the words used in the text. This information seems applicable to readers who use software documentation for reference, perhaps needing to know details or short information. If we want to treat everything on an equal level to encourage verbatim memory, Huckin (1983) suggests listing the information. Using short paragraphs or series of sentences on separate lines might work also. We should note also that memory for detail decays faster than memory for gist, the. information at a higher level in macrostructure (Kintsch and Van Dijk 1978, 393). Since much of software is detail, what can we do to encourage remembering it? Or do we just provide quick access to it? or do we use a combination of text presentations that encourage both memory for gist and memory for detail? 42

PAGE 51

In summary, then, the following cognitive factors need to be considered in analyzing software documentation: Type I or Type II Processing: Do the authors use strategies to encourage immediate recall and application of the material (Type I processing) or do they use strategies that enhance learning of concepts useful for problem solving and long-term recall (Type II processing)? Use of Schemas: Do the authors invoke pre-existing knowledge by using analogies and situations already familiar to the reader? Do the authors help readers build new schemas by making clear connections between old information (e.g., analogies and models) and the new information to be learned? Do they use the scenario principle to help readers incorporate new information into the natural structure of agent-action? Text Processing: Do the authors provide cues to the macro-organization of the text, either by following the expected structure of a genre or by using titles, suheadings, and topic sentences to make the hierarchical structure clear to the reader? Do the increase the readers' efficiency in processing at the micro-level by using devices for coherence and not requiring bridging inferences? Is the text structured to encourage memory for gist by using longer paragraphs in a series, or 43

PAGE 52

memory for detail by using short paragraphs, sentences, and lists, which place equal emphasis on each item? These cognitive factors guide the mental processes that readers use to learn from a text. We next consider rhetorical features of a text and how these might also affect the way readers respond to and use software documentation. Rhetorical Factors Three overlapping areas of study--rhetoric, discourse analysis, and text linguistics--offer another perspective for analyzing documentation. Although these disciplines have not been subjected to as much empirical research as cognitive psychology, they do provide a means of differentiating-texts and the quality of texts. For convenience in discussing the rhetorical factors used in this analysis, I've chosen to follow, in part, the framework constructed by de Beaugrande and Dressler in their Introduction to Text Linguistics (1981). In addition to cohesion and coherence, de Beaugrande and Dressler examine standards of textuality under the headings Intertextuality, situationality, Informativity, and Intentionality and Acceptability. These four topics encompass much of the same material considered in modern rhetoric and discourse analysis. 44

PAGE 53

Intertextuality Text or typology of texts--is a major concern of modern rhetoric. As we've seen, text type also guides the cognitive processes of readers, who use the expected structures of the text to decide what's important and to build a mental text base. Therefore, we need to look more closely at intertextuality--how does a text compare to other texts within its class and without? The characteristic most frequently used to identify text types is purpose. It is the distinguishing characteristic of Aristotle's Rhetoric: discourse used to persuade an audience. Modern rhetoricians use the term rhetoric to include all discourse, even the dialectic (logical discussion) which Aristotle separated from rhetoric. Kinneavy (1971), for example, defines four 11aims11 of discourse: reference, persuasive, literary, and expressive. These aims are comparable to four of the six categories named by Jakobsen: reference, conative, poetic, emotive. The other two categories are phatic (direct address to the reader) and metalingual (comments on the discourse itself) (Harris 1983, 149-150). The emphasis of the four main categories is on a different element in the basic communication model--encoder, decoder, reality, -and signal (Kinneavy, 18). The same elements are present in Laswell's famous model: Who says what in which channel to whom and with what effect 45

PAGE 54

(Barnett and Hughes 1985, 44). Thus reference discourse emphasizes the what--the reality signified--and its main purpose is to communicate information about that reality. Persuasive discourse emphasizes the whom, and its main purpose is to move the decoder to action or belief. Literary discourse emphasizes the channel or signal--the way in which the messages is presented. Expressive discourse emphasizes the who, and its main purpose is to communicate information about the encoder. Beale (1987) takes a slightly different tactic in A Pragmatic Theory of Rhetoric, in which he's concerned primarily with "What human beings do with the discourse, rather than with the linguistic and cognitive factors that underlie the doing [author's italics)" (1). He classifies discourse based on two dimensions: whether or not the text designates experience (referential texts) or symbolizes experience (non-referential) and whether or not it reflects on experience (contemplative) or participates in experience (active). Beale calls these motivational axes and contrasts his classification with K. Burke's use of action, actor-agent, scene, means, and purpose in a Grammar of Motives. He labels as scientific those texts that are referential and contemplative; instrumental texts are referential and active; poetic texts are non-referential and contemplative; and rhetorical texts are non-referential and active. 46

PAGE 55

Beale, like Kinneavy, places genres within these categories. Thus scholarly theses are scientific; short stories, novels, and drama are poetic; instructional texts are instrumental; and political speeches are rhetorical. De Beaugrande (1980) adopts a more complex classification of text types, examining the "distinct configuration of relational dominances obtaining between or among elements of: (1) the surface text; (2) the textual world; (3) stored knowledge patterns; (4) a situation of occurrence" (197). His classifications are descriptive (concerns objects and situations) ; narrative (concerns events and action in ordered linkage) ; literary (alternativity to real world); poetic (akin to literary, but with "interlevel mapping options"); scientific (optimal match to real world) ; didactic; and conversational (episodic, a range of sources for admissible knowledge). Since software documentation falls within the didactic category, de Beaugrande's full description sheds further light on the nature of this discourse: The textual world must be presented via a process of gradual integration, because the text receiver is not assumed to already have matchable knowledge spaces that a scientific text would require. Therefore, the linkages of established fact are problematized and eventually deproblematized (198). 47

PAGE 56

Once a given reader has read a didactic text, it has been "deproblematized" and will no longer function the same way for that reader. In each of these classification systems we can locate how-to-discourse: informative, a sub-category of referential in i
PAGE 57

instructions or to build a lasting conceptual, impression (Ramey 1988, 153). Reference manuals are not meant to be read cover to cover, as a tutorial might. Instead they're organized for quick access. They may not have lengthy explanations because the reader will already have some familiarity (a working knowledge) with the program when the manual is consulted. The user's guide, as described by Major (1989), sounds more characteristic of Major's own operation in an academic computing center. His user's guide is for the whole center, and thus points the way to all the other resources available to users--reference manuals, operating procedures, and tutorials. It lays the groundwork for using the other texts and it gives an overview of related topics. This use of the term seems more specialized than user's guides I'm familiar with, which are often for a specific product and combine the characteristics of tutorials and reference guides. What's important here is not the various classifications per se, but the fact that (1) readers invoke different global processing strategies depending on the genre (Kintsch and Van Dijk 1978, 389; de Beaugrande 1980, 199) and (2) since the text may have share characteristics with texts in other genres, readers may adapt their processing strategy accordingly. For 49

PAGE 58

example, a manual that uses a great deal of narrative structure may draw the reader into employing a story schema to process the text. This approach could be useful. As Kintsch found in a 1975 study, subjects had a 11better memory for history paragraphs which were of narrative form than for more descriptive and unfamiliar science paragraphs11 (Kintsch 1982, 192). Readers look for cues about the text type both outside the text (e.g., the situation in which they're using the text) and inside the text. cues outside the text would include oral instructions given during a training session (as in experiments by carroll, Smith Kerker, et al. 1988) or offered by the sales clerk for the software. Cues within the text include direct instructions.to the reader, the topic itself, or a characteristic title. For example, The Adventures of Huckleberry Finn suggests a different processing strategy than The New York Public Library Desk Reference Guide. Even within.the narrower genre of software manuals, a title such as Fast Access to Word Perfect 5.0 suggests a different expectancy structure to the reader than VAX/VMS User's Guide or simply The Retailer. A title like User's Guide emphasizes that the main purpose for the reader is to the equipment or software, not to read the text. The manual is secondary, whereas in other genres, especially literary, reading the text may be an end in 50

PAGE 59

itself. If readers don't find cues for text types, they're 11probably able to utilize [the] texts but efficiency suffers, and the mode of interaction of .speaker/writer and hearer;reader remains vague11 (de Beaugrande 1980, 199). Mixed Genres. Harris (1983) makes a case for the importance of mixing persuasive elements in how-todiscourse. Using the three means of persuasion set forth by Aristotle--ethos, logos, and pathos--she explains how each contributes to the successful how-to text. She finds evidence of ethos when writers present themselves as believable experts, qualified to tell readers how to use the software. An ethical writer does so accurately, including only truths and not excluding any truths that would be important to the reader (for example, forgetting to say press Enter). In addition, the writer's character is demonstrated through evidence of empathy for the reader. Writers demonstrate empathy for the learners' situation by making the text easier to use and learn from, perhaps incorporating many of the elements discussed under cognitive factors. Harris minimizes the evidence of persuasion through pathos, relegating emotional appeals to the use of 11reassurances, warnings, [and] appeals to pride and ambition11 (152) She considered these less important 51

PAGE 60

than the persuasive appeal of ethos, which in turn is based on logos, the persuasion of logic. Logos becomes persuasive when the writer uses inductive reasoning ("If you do this, then this will happen") and deductive reasoning ("This is so: therefore you must") (153). However, the conclusions drawn from the reasoning must be true. Otherwise the text fails to refer accurately to reality, and the writer's ethos suffers. (It is not my purpose here to analyze whether the texts are accurate reflections of the software program--I'm going to assume that this criterion is met, by virtue of the manuals' acceptance.) Harris considers how-to discourse a special case of persuasion, since it is not meant to incite action. She assumes the reader is already sufficiently motivated to reach the goal of instruction. Why else would they read the book? Sometimes, however, reader might lack motivation to use a text to learn. If the task seems overwhelming, readers may put off learning. Some how-to books, such as Auto Mechanics for Dummies, do make a point of convincing readers that the task is easy, promising that "you too can change the oil in your car and save hundreds of dollars." Sometimes we read directions to find out if we want to do something. For example, we might read a recipe to see if it is worth making. Persuasive techniques can also allay people's 52

PAGE 61

fears about using .the software. If learners are anxious and tense, they are less likely to process information at the intellectual level (Hand 1982, 111). Situationalitv De Beaugrande and Dressler's (1981) discussion of situationality, "the factors which render a text relevant to a current or recoverable situation of occurrence" (163), pertains primarily to conversation where the participants, who are physically present, comment directly on their immediate circumstances. A few concepts regarding situationality bear mentioning in the context of software documentation. First, a situation is frequently mediated, that is, the participants feed into it their own beliefs and goals. If the beliefs and goals of the participants are relatively well matched, then the text is used to monitor the situation, "to provide a reasonably unmediated account of the situation" (de Beaugrande and Dressler 1981, 163). For example, if both writer and reader believe that learning to use the software is a valuable and attainable goal, then the writer can present the information in a straightforward fashion, without having to change the readers' beliefs. If, however, readers resist learning to use the software, questioning its usefulness and their ability to 53

PAGE 62

understand it, the writer may need to manage the situation, to "guide the situation in a manner favourable to the text producer's goals" (de Beaugrande and Dressler 1981, 163). The writer would have to use strategies to persuade and encourage cooperation. Or as de Beaugrande and Dressler suggest, "downgrade the expenditure of time and resources that others must make to further your own goal" (178). On the other hand, the writer could perceive the situation as qifficult for the reader and present it is as such. If the readers don't agree, they might reject the situation presented (monitored) by the writer and instead manage it by reading with their own goals in mind, ignoring (and possibly resenting) text that doesn't fit their mediated version of the situation. Informativity De Beaugrande and Dressler (1981) use the term informativity "to designate the extent to which a presentation is new or unexpected for the receiver" (139). The definition relies in part on the mathematical theory of communication which determines the shortest signal needed to sen4 a message that's unpredictable. On one hand, an unexpected message is said to be highly informative ("The governor was shot today") but a predictable message ("Students and bar owners object to 54

PAGE 63

raising the drinking age to 21") contains little or no information. The dilemma for writers of informative discourse, which by its nature must contain what is new to us (Kinneavy 1971, 20), lies in the readers' ability to process unpredictable or new information. If writers present too much that is new, the text is difficult to process ( Haviland and Clark Kintsch and Van Dijk To keep informative text from becoming too difficult, de Beaugrande and Dressl.er suggest that writers rely on five "expectations" about a text. First, readersexpect the text to reflect the existing knowledge of the real world and "normal ordering strategies for and talking about the world" such as spatial and temporal patterns for describing scenes, events, and objects (147). Second, readers depend on syntax, the normal ordering of sentence elements. Third, readers expect to find new information near the end of a clause and old information (low informativity) near the beginning of a clause, sometimes connected to previous sentences through pro-forms (see also Haviland and Clark 1974). "These two techniques [given/new] provide a balance between opposing tendencies: maintaining a clear point of orientation, and keeping informativity reasonably high" (149). Fourth, readers have expectations about text types as discussed 55

PAGE 64

under "Intertextuality." Fifth, readers have expectations from the immediate context in their using the text. Writers can use these expectations to prevent overwhelming readers with new information in instructional text. In conjunction with balancing expectations and givenjnew information, writers must select and arrange the information appropriately. Kinneavy (1971) notes that writers may choose to be less selective and more comprehensive. The more comprehensive a text is, the more informativeness it may have. Reference texts with alphabetically presented topics promise that they cover everything from A to z. However, what writers choose to include or exclude could be based on a more pragmatic consideration of the reader: What do readers really need to know for the task at hand? Harris (1983) differentiates between two organizing principles, semantic based and pragmatic based. Text organized around semantic considerations emphasizes the reference to reality. The organization could be temporal, as in a sequence of steps to take in a procedure. It could be spatial, as in a description of parts or materials needed for a procedure. In combining temporal and spatial organization, writers must decide which comes first. Harris suggests that in general, if the context is simple rather that complex, put the 56

PAGE 65

description first. If the context is complex, the two patterns might be alternated. A software manual is semantically organized if it describes the parts of the software, e.g., describing software commands in sequence. It is pragmatically organized if it is centered around tasks that the reader is likely to perform. In pragmatic-based organization the writer considers what is best for the audience's needs. For example, the scenario principle, mentioned earlier, is clearly more relevant to the audience's needs than simply defining or describing. The description of a command for deleting text in a word processing program is not as helpful as saying, "You can delete a paragraph by doing thus and so." Sometimes a pragmatic consideration such as providing easy access to information will also dictate organization. In this case, listing commands from A to z makes it easy for readers to look something up. This pattern takes into account the fact that users might not read manuals by starting at the beginning and reading to the end. For the organization of sections within a manual, Ramey (1988) has found that readers prefer seeing information at the novice level presented separately from more advanced information and that readers want various kinds of information--overviews, summaries, procedures--57

PAGE 66

differentiated typographically. ln a program for user feedback, Gibson also found that readers prefer theoretical information separated from procedural information (Shriver et al. 1986, 97). The basic questions for software documentation, then, concern how new information is added to the readers' existing knowledge (or increasing knowledge), how much new information is included, and whether the information is organized around the software product (semantic) or around the readers' needs (pragmatic) Intentionality and Acceptability Another key to the success of a text lies in the relationship writers establish with their audience--the roles they set for themselves and that they ask their readers to play (Ong 1975; Park 1982; Ede and Lunsford 1984). The willingness of each to play their.roles has been called "the cooperative principle" by Grice (cited in de Beaugrande and Dressle:r 1981, 118). In the case of software documentation, readers turn to a manual because they need help learning to use the program; they are willing to play the role of learners, to read, and to use the text. The manual writer has agreed to supply the needed information and in doing so agrees to be truthful, but also to be helpful, to be empathetic to the learner's difficulties and to provide help in a way that enhances 58

PAGE 67

learning, as discussed under cognitive factors. If the writers intend something other than help for the reader, for example, to show off their own expertise, then the I reader may no longer accept their text. This contract is what de Beaugrande and Dressler refer to as intentionality (on the part of the writer) and acceptability .(on the part of the reader). Besides a failure to cooperate, the relationship between writers' intentions and readers' acceptance can breakdown if writers violate Grice's other "maxims." Writers must agree to abide by the maxim of quantity, to be "as informative (but no more informative than) is required." They agree to maintaining quality, to be truthful, not saying what is false and not omitting a truth that's needed. They agree to be relevant, saying what is related to the topic and what "would be useful in attaining some goal." Writers also uphold the maxim of manner, to be plain and to be clear in "ways to arrange and deliver texts," to "avoid obscurity of expression," and to "avoid ambiguity" (de Beaugrande and Dressler 1981, 118-119). To establish a relationship with a reader, writers have to decide who they are and who the readers are. The question of who the readers are has been answered with a dichotomy: readers are people who actually read the text and those whom the writer imagines are reading the text 59

PAGE 68

(Ong 1974; Park 1982, Ede and Lunsford 1984). Unless we take a survey of people who have bought either the software package or the secondary documentation, we don't know who the real audience is. We can only imagine them, as the writers may have done. But we can use clues within the text to discern the role that writers cast for themselves and their readers. We can look to see if the authors have revealed their identity by stating their names on the cover or title page, or, at the very least, in the acknowledgements. Do the writers openly admit their role in the relationship or is it obscured behind the name of a software corporation or publishing company? If readers don't see a name, they may not feel they are being addressed by a person, and they not take the trouble to play their role or work on their side of the relationship. The author's lack of identity may not be significant for everyone. It may be more critical if documentation is directed at general, non-technical readers. In an experiment and survey involving 300 college students in England and a text based on biology, "the humanities students were most adept at remembering the author's name (67%) and the engineers were the lowest (38%)11 (Ramsey 1980, 112). While knowing the author's name may not correlate directly with better comprehension of a text, 60

PAGE 69

grammatical voice and person do. Ramsey found that the highest scores for comprehension of the text correlated with versions written in the first person, active voice ("I concluded that 11) and the lowest scores with third person passive ("It was concluded that ) On the other hand, the fastest reading time was for third person active ("The scientist concluded that ."),a construction that corresponds with the more common narrative structure of stories. The slowest rate of reading correlated with the first person passive, "probably because 'Thus-and-so was done by me' is usually a rather.circuitous manner of expression" (112). All students, regardless of academic field, who read versions in the first person, both active and passive, scored higher at remembering the author's name than those who read the third person version. Remembering the name may not be important, but comprehension is. Since a text written in the first person yields greater comprehension, it seems ridiculous for such a text to obscure the author's identity. Perhaps writing in the first person is not essential to software documentation. There's not much need to say "I did this or that," except perhaps in metadiscourse such as "In the following sections I [or we] discuss the main functions". As we've seen from Kinneavy's categories of rhetoric and Harris' analysis, the emphasis 61

PAGE 70

in instrumental writing is mainly on the subject talked about (it) and secondarily on the reader being persuaded. Rarely is the emphasis on the person writing, as it is in expressive discourse. However, if writers directly address the reader as "you," they have implied a first person who is doing the addressing. Thus writers of software documentation have reason to introduce themselves with a by-line. Gibson (1966). uses grammatical person and voice to judge whether a writer's style is tough (active "I" talk), sweet (active "you" talk) or stuffy (passive"it" talk). Although Gibson analyzes contemporary prose primarily in novels, essays, journalism, and advertising, not instructional text, his criteria for labeling the three styles can still be used to judge the personality of the writer and the writer's relationship to the reader. Some criteria, such as number of syllables in words, are reminiscent of readability formulas. Others, such as use of personal pronouns, people as subjects, number of adjectives, verb forms, contractions, and abundant punctuation, including parentheses, reveal more of the writer's personality. None of these styles sounds particularly desirable. Tough is egocentric, perhaps even simple-minded; sweet may cater to readers too much, sounding chummy; stuffy doesn't care about the reader at all. Gibson advocates 62

PAGE 71

being serious without being stuffy; writers should act like human beings. His specific advice (108) resembles that given in "Principles for Writing Sentences" in Guidelines for Document Designers et al. 1981). Mirel (1988) examines ways in which documentation writers can use syntax to affect the relationship between writer and reader. She identifies two kinds of relationships: instructor and learner; commander and follower. The instructor is more likely to encourage readers to explore, take time, and give themselves room for mistakes and practice. The commander may expect instant obedience, not allow for mistakes, and may not be as tolerant of the learner's need for background information. For an empathetic bond between writer and reader, Mirel suggests using active voice and imperative mood, but tempering them with modalities or declaratives occasionally. She recommends avoiding the use of declarative sentences only, passives with deleted agents, and modalized auxiliaries. Passive verbs protect the anonymity of the doer, whether it is the writer taking responsibility for some action or the reader who is supposed to take action. Passives direct the readers' attention away from being a participant and toward the phenomenon being discussed. For example, in "The printer must be turned on," the emphasis is on the printer and there is no mention of who should turn it on. Compare 63

PAGE 72

this to the sentence "Be sure to turn the printer on before you begin asking for the report." Mirel also suggests limiting the use of noun compounds and jargon, which may intimidate the novice and block understanding, and to mix friendship with authority by using colloquialisms; contractions; "please"; and modalizers such as possibly, probably, and certainly. One key place to look for how the author establishes a relationship is in the opening passages (Gibson 1966). Here the writer establishes what it is about the topic that is important to the reader, what purpose the reader may have for using the text, and what roles both writer and reader are expected to play. The opening passages may also permit more expressive language in which writers can reveal a persona, which may or may not be acceptable to the reader. To summarize the rhetorical factors, the following basic notions may influence how readers respond to software documentation: Intertextuality: To what extent do the texts share characteristics with texts from other genres, particularly with-persuasive texts? How might overlapping genres affect the readers' processing of the texts? Situationality: How do the authors monitor the situation, that is, what beliefs of their own do they 64

PAGE 73

present to the reader? To what extent do the authors try to control the situation? Informativity: Have the the authors balanced old and new information to keep the text informative without overwhelming for the reader? How comprehensive have they chosen to be? Is the content organized semantically or pragmatically? Intentionality and Acceptability: What roles do the authors cast themselves in? What roles do they assign to readers? What characterizes the author's voice? By examining these text features, as well as features that influence cognitive processing, we should be able to discover in what ways the texts from publishing companies are similar to or different from the documentation supplied by the software manufacturers. 65

PAGE 74

CHAPTER 3 ANALYSIS OF THE DOCUMENTATION The analysis of the two sets of documentation follows roughly the same order used to discuss the cognitive and rhetorical factors. I've attempted to examine each text in turn, first the documentation from WordPerfect (a looseleaf reference volume titled WordPerfect and a paperback titled WordPerfect Workbook) then the documentation from Que (a paperback titled Using WordPerfect 5), followed by the manuals from Lotus (three paperbacks titled 1-2-3 Getting Started, 1-2-3 Tutorial, and 1-2-3 Reference Manual) and the one from Sybex (a paperback titled The ABC's of 1-2-3, Release 2.2). The presence of some characteristics in a text and the absence of others sometimes skew the analysis so that each text is not always given equal treatment. For a visual reference, I've included in Appendix A a two-page representative sample of each text. Cognitive Factors In analyzing the texts to see how each facilitates learning, I've examined three areas: the depth of processing that is encouraged for remembering, the extent

PAGE 75

to which the authors use schemas, and the strategies for structure and coherence that facilitate text processing. Because I am primarily concerned with how individual readers use these texts to learn on their own, I have largely ignored the reference manuals from WordPerfect and Lotus, and concentrated on comparing the workbook and tutorial with the texts from Que and Sybex. Depth of Processing To what depth do these texts encourage processing? Do they help readers build a conceptual understanding that's useful for problem-solving, or do they foster learning for immediate recall and use? In looking at the texts, we can easily see that they do both, with varying degrees of emphasis. All of the texts present step-by step procedures, set off in bold (in 1-2-3 Tutorial) or clearly enumerated (all others). This formulaic approach does not usually encourage long-term memory for concepts (Mayer 1982) nor does it encourage memory for gist (Kintsch and Van Dijk 1978). Instead, the listing approach supports Type I processing for immediate recall and use. Nonetheless, since readers execute the steps--not merely read them--by typing at a keyboard and interacting with both the text and the computer, another level of processing is operating. The readerjuser is practicing 67

PAGE 76

the commands, associating the information with a kinetic and visual experience so that learning is not just semantic but is episodic as well. Do these step-by-step procedures function like exercises then, becoming an elaboration strategy for transferring information to long-term memory? Perhaps, but the research of Charney, Reder, and Wells (1988) suggests that tutorial problems alone do not encourage the same efficient learning as do tutorial problems combined with exercises that students work out for themselves. In the four texts analyzed, all but the Que book used controlled tutorial problems throughout. The reader is shown a worksheet or document to type in, or, as in WordPerfect Workbook, an actual disk file to use. It's only in later chapters, such as the one on working with columns, that the Que book suggests readers work with their own documents. Interestingly enough, the Que book for Lotus 1-2-3, which is the Lotus book but not one of the four analyzed, uses examples, not tutorial problems per se, and no enumerated procedures. If the analyzed texts all encourage Type I processing, do they differ in their use of strategies for deeper processing? They all introduce each chapter with some kind of familiar information before presenting the formulaic, step-by-step instructions; however they differ in the type of familiar material presented. WordPerfect 68

PAGE 77

Workbook begins by describing a typical office typing situation that requires a particular kind of document, a memo or itinerary or legal brief. Using WordPerfect describes a benefit that the software offers and then gives a preview of what's covered in the chapter. This same approach, in considerably fewer paragraphs, is used by 1-2-3 Tutorial for chapter introductions, with a two or three sentence preview at the beginning of each lesson. The ABC's of 1-2-3 consistently begins every chapter with from two paragraphs to several pages of introductory material, but the kind of material is not consistent. It sometimes describes a situation readers might find themselves in ("Imagine how frustrated you would feel if .. 11), extols a benefit of the program, previews the chapter, or gives general conceptual information before the next section which is always titled, "How To" do something. The texts that begin with a typical situation are invoking a script or procedural schema which helps the reader assimilate new information; those that present a preview or generalized information are providing the reader a structural schema for processing the text. But how does stating benefits, as Using WordPerfect and The ABC's of 1-2-3 do in the introductory information, affect depth of processing? Perhaps benefits remind readers of the goals they have in learning and thus not only help 69

PAGE 78

readers integrate the new information but also motivate them to continue. Stating benefits can also assuage cognitive dissonance if readers have become dissatisfied with the product and discouraged about learning. The technique of inserting questions to help readers read with a goal in mind is not used by the authors. In a few isolated cases the authors of Using WordPerfect use questions in a heading, for example, "What Hardware Do You Need to Run WordPerfect?" (15). This usage is more in anticipation of the readers own questions, than as a guide to learning. The same is true when the authors ask rhetorical questions within a paragraph to introduce the material that follows. For example, the authors of The ABC's of 1-2-3 ask "Where should you put the new column?" (98) when beginning an explanation of inserting columns. Invoking Prior Knowledge All of the texts used the obvious analogies or models for describing how the software works: the manual methods for performing thesame tasks. For WordPerfect, this was the typewriter; for Lotus 1-2-3, it was the accountant's columnar pad, pencil, eraser, and calculator. This analogy was used least often in the documentation from WordPerfect Corporation, and then usually in the Reference Manual for describing differences between typing with a typewriter and typing 70

PAGE 79

with a word processor. In the other texts, the analogy was referred to throughout. The authors of the Que and Sybex books frequently use original analogies to convey a point. The author of Using WordPerfect quotes a clever comparison offered by the the vice-president of WordPerfect Corporation to describe the uncluttered (but "austere") editing screen: "What makes WordPerfect attractive is that it gets out of your way. It's like a well-mannered house guest who is kind enough not to disrupt your life or the way you do things. 11 In explaining the importance of identifying computer equipment to the Lotus program, the authors of The ABC's of 1-2-3 compared the software program to a blindfolded bicyclist who doesn't know what kind of bike he's riding. They also speak of Help screens as a builtin lifeguard "to save you from drowning in confusion" (39). such analogies and metaphors enlivened the text, but they did not aiways seem consciously employed as a model to deepen On the other hand, the analogies to a typewriter or accountant's ledger could explain functional aspects of the software, and they invoked a procedural schema for how to use the tool to get a job done, the kind of procedural knowledge that Rumelhart and Norman (1981) say we're aware of but cannot usually put into words. Two of the texts, Using WordPerfect and The ABC's of 1-2-3 71

PAGE 80

emphasize the schema we have for a particular task-writing a letter or creating a cash flow projection--in addition to our schema for using a tool. Consider the subtle difference between these two statements: (1) However, since the worksheet is often used for a budget in one form or another, the following instructions show you how to set up a budget. If you want to set up your own budget later on, the budget you will build in this book will give you the skills and confidence to do so. (From the introduction to Lesson 8, The ABC's of 1-2-3, 32) (2) Chapter 2 focuses on the specific tasks that you perform as you build a sample worksheet. While you are building the worksheet, you learn how to enter text and numbers, write formulas, and change the worksheet's appearance. (From the introduction to Chapter 2, 1-2-3 Tutorial, 17) The first one, from the introduction to from The ABC's of 1-2-3, emphasizes the work assignment, the larger context of creating a budget. The introduction from 1-2-3 Tutorial emphasizes the particular Lotus skills that readers will learn. While each declares a slightly different emphasis, in practice the authors of both these texts maintain about the same ratio between references to the work assignment and instructions for learning Lotus commands. They just include the information in slightly different places. The ABC's of 1-2-3 consistently places work scenarios pefore the step-by-step how-to information; 1-2-3 Tutorial places some scenarios in the introduction, some mixed with the how-to steps, and some 72

PAGE 81

in the summaries at the end. The author of WordPerfect Workbook always invokes work schemas only within the one or two short introductory paragraphs, and the summary lists only skills learned for using the software, not their application. By sharp contrast, the authors of Using WordPerfect frequently invoke the global schema or script that readers (who are also writers) have for the entire process of writing. They do not simply show how WordPerfect makes it easy to produce finished letters, memos, and other documents; they include long paragraphs and pages to discuss the composing process, from idea generation to outlining to drafting, revising, and proofreading. This practice is more conspicuous in the first two or three chapters, but it's also present in later chapters such as "Assembling Document References." Readers thus have much more opportunity to relate instructions about using WordPerfect commands to their own knowledge about writing. In a sense, the authors of Using WordPerfect are elevating the program concept to a higher level--from word processing to writing process. In summary, then, all the authors were more apt to invoke task schemas as mode.ls than to use metaphors or analogies; and they did so with varying degrees of emphasis. Using WordPerfect invoked schemas more than any other text did and it did so at a higher conceptual 73

PAGE 82

level, the composing process itself. The ABC's of 1-2-3 sometimes referred to global concerns in designing a spreadsheet, but more often it made liberal use of task schemas. 1-2-3 Tutorial referred to task schemas throughout each lesson, but did not elaborate on them. WordPerfect Workbook invoked a task schema rather perfunctorily at the beginning of each lesson and then did not offer additional conceptual information. Building New Schemas Perhaps the prime means of helping readers build new procedural schemas comes from the use of tutorial problems, as discussed earlier. While readers who practice each of the steps in the tutorial may not be committing every step to memory, they are building a procedural script for how to use the software. Both of the Lotus texts, in introduce the worksheet by guiding the readers through a series of steps designed to show how to move the cursor from cell to cell in the worksheet. This movement is a basic schema needed for creating and working with spreadsheets. All of the texts encouraged using and practicing the procedures to build a new schema for "how to" use the word processor or spreadsheet program. Not all of the texts, however, consistently applied the scenario principle to build schemas by focusing on 74

PAGE 83

agent-action. A quick look at headings in the table of contents and at headers or footers reveals the following patterns: Using WordPerfect: Except for 12 entries at the top of the first page (out of 14 pages for table of contents) every major section, chapter within a section, and heading within a chapter uses gerunds to express action, e.g., Inserting Blank Lines, Editing a Document, Working with Blocks. Of the 12 exceptions, five are stated as questions the user might ask, e.g., "Who Should Use This Book?" and two are are stated as "How to" and "Where to." Headers are book title (even pages) and chapter title (odd pages)--a format that the authors themselves suggest to use in their instructions for creating headers and footers. The ABC's of 1-2-3: Half of the headings for the eight major parts and all but three out of 67 lesson titles begin with gerunds (as well as the lesson number) Every lesson also has a section titled "How to" do something. Headers are the major part title (even pages) and lesson title (odd pages). 1-2-3 Tutorial: Every chapter title and every subheading (except summaries and seven others out of 114) begins with a gerund. Footers are the chapter titles. WordPerfect Workbook: Only two out of six section headings begin with gerunds; the others are nouns or noun 75

PAGE 84

plus adjective. Every lesson title, in addition to the lesson number, is a noun or noun plus adjective. However, the majority of lesson subheadings, which are not shown in the table of contents, do use gerunds to identify a task, e.g., "Using the Delete Key" and "Copying a Single File." Footers are simply the lesson number, not title. A bias toward agent-action definitely exists at the sentence level. All of the texts frequently address the user directly by using imperative verbs. It's almost impossible for the reader to escape being an agent! All of the texts also construe the programs as an agents. Thus, the agent-action scenario includes what the program, as well as the user, is doing. Examples such as the following were common: "WordPerfect first takes the number entered in. column c" (Using WordPerfect, 548); "WordPerfect creates several files of its own" (WordPerfect Workbook, 87); "The ;worksheet titles command remed"ies this before or after you split the screen" (The ABC's of 1-2-3, p. 123); 111-2-3 prompts you to enter the graph name" (1-2-3 Tutorial, 55). Facilitating Text Processing How do the authors help the reader build a mental macrostructure of ideas about the software? As mentioned earlier, authors of two of the texts, Using WordPerfect 76

PAGE 85

and 1-2-3 Tutorial, are particularly conscientious about always using previews as part of the introduction to each chapter. In Using WordPerfect the topics to be covered are sometimes presented as a bulleted list and sometimes within a paragraph. In 1-2-3 Tutorial, previews are presented in only one sentence or a very short paragraph, but they accompany every chapter. WordPerfect Workbook sometimes mentions what a lesson will cover (in no more than a sentence), sometimes just reviews a previous lesson, and sometimes describes the situation that the reader is in. Beneath the title of every chapter heading, The ABC's of 1-2-3 provides a short list of the (one to six items) covered in that chapter. Introductory paragraphs also function as a preview to the extent that they generalize about the commands described in the how-to section. Every chapter in The ABC's of 1-2-3 follows the same pattern: introductory paragraphs or pages followed by a section titled "How to" do something. It is a pattern the reader can count on and process accordingly. In these manuals, the plentiful headings and subheadings serve as the most important clues readers have to discern macrostructure and to build a hierarchical mental text base. Clues in the running text may be harder to find since the running text is almost non-existent. This is especially true for WordPerfect 77

PAGE 86

Workbook and 1-2-3 Tutorial, which rarely have more than two to three short paragraphs strung together before being interrupted by procedural steps. The ABC's of 1-2.J. does have up to three pages of short--one to five sentence--paragraphs before the procedural section. Using WordPerfect often has several paragraphs, or even pages, of running text. These appear at the beginning of each chapter, but they are also intermixed with the procedural material. This choppy format makes it difficult for readers to generalize at higher levels. Instead it encourages readers to remember detail, as Kintsch and Van Dijk (1978) have observed, although that detail could be grouped in memory under topics (schemas) such as 11how to widen a column of figures" or "moving a block of text." Even though the texts are not continuous, they are generally coherent. I analyzed coherence in representative paragraphs from the beginning of a chapter in each text, examining devices such as repetition, proforms, synonyms, logical connectives, topical focus, and givenjnew patterns. I also looked at the hierarchy of sentences, using Christensen's "Generative Rhetoric of a Paragraph" (1967) to show co-ordinate and subordinate sentences. Analyses of the sample paragraphs appear in Appendix B. 78

PAGE 87

The samples show strong use of repetition to maintain coherence. The texts for WordPerfect provide more devices for coherence; the texts for Lotus 1-2-3 have some weaknesses and require readers to use more processing resources. WordPerfect Workbook has as a strong subordinate sentence pattern and uses instantiation as a logical connective. Using WordPerfect also uses instantiation and it uses parallel structure to coordinate sentences. The sample from 1-2-3 Tutorial has a top level sentence that presents new information as the subject, shifting the focus away from the previous topics, 1-2-3 and "you" the reader. The sample from The ABC's of 1-2-3 has the least coherence. Because given information isn't readily apparent, it requires readers to make bridging inferences, a process that consumes resources in shortterm and long-term memory. It also uses less repetition to strengthen coherence. Generally, in the area of cognitive psychology, the texts use strategies to help readers learn from text. Both sets of texts encourage Type I processing for immediate recall and use; but the secondary documentation, particularly Using WordPerfect, offers more conceptual material--analogies, schemas, application to real life tasks--to encourage Type II processing for long-term memory and problem solving. All the texts use 79

PAGE 88

titles and headings to maintain topical focus and to surface the macrostructure, thus helping readers build mental hierarchies. Use of devices for coherence, which aid readers in the microprocessing of text, varies from author to author. Table 3.4 at the end of this chapter shows the relative strengths of each text. Rhetorical Factors An analysis of cognitive factors shows how the representation of meaning within the texts helps readers create their own mental representations. For the most part, an analysis of rhetorical factors--intertextuality, situationality, informativity, and intentionality and acceptability--shows how context influences readers' learning. Intertextuality A quick visual analysis, along with a reading of the titles, tells readers that these texts clearly belong in the instructional category. The layout of the text with its frequently indented left margin, liberal use of white space, and bulleted and numbered steps--all suggest functional material. The numbered steps, especially, imply procedures to be followed. Packaging is also a clue to the text's category and perhaps influences readers' interaction with the text. 8

PAGE 89

Both of the secondary texts have the look and feel of quality paperback books you'd expect to find in a bookstore. They are within a quarter inch of the same height and width (9" by 7 3/8"), and both have vibrant, four-color covers with a photo. The Que book, like the documentation from WordPerfect, also had a reference card, registration form, and order blanks to tear out. They could almost be bedtime reading, something you might slip into. The multiple volumes from the manufacturers are packaged as products, in a case with the disks. with the multiple volumes. They look like something to be taken seriously. The Lotus texts were only fractionally taller and wider than the Que or Sybex books and their covers had solid, backgrounds with I I white letters. The reference volume from WordPerfect was I I in a three ring, cloth binder, with blue letters. I The workbook had a four-color photograph with a white background, but only a few highlights of color. These texts were the same height and width, but an awkward one inch wider than the Que or Sybex books. Titles, along with visual format, give readers another clue to processing the text. "Using WordPerfect11 indicates that the readers will be able to do something with WordPerfect if they read the book. "WordPerfect Workbook" even implies that they might do something while reading the book, although "workbook" suggests that 81

PAGE 90

readers do the work in the book, not necessarily on a computer. "The ABC's of 1-2-3" hints at the beginning steps of learning something basic, a primer approach. This title reminds readers that, to learn something new, they need a "beginner's mind"--a hard state for adult learners to accept when they're used to being experts on the job. "1-2-3 Tutorial" promises to teach readers in step-by-step fashion. Additional documentation from Lotus and WordPerfect bears the titles "Reference" and "Getting Started." For Lotus they are two separate volumes. For WordPerfect they are contained in one binder, titled simply--and ambiguously--"WordPerfect." Thus, buyers of the original software can choose which text to use depending on their purposes. For the most part, the texts only rarely exhibited characteristics of texts from other categories as identified by Kinrieavy (1971) and Beale (1987). The authors of The ABC's of 1-2-3 and WordPerfect Workbook occasionally used a role playing technique that thrust readers into a small drama. They used the present tense to set the stage: "A memo needs to be sent to all department mangers, informing them of the tentative plans for the regional marketing 6onference" (WordPerfect Workbook, 27) and "A few seconds ago, a colleague walked into your office with revised figures. It turns out that you've been making predictions with outdated information" 82

PAGE 91

(The ABC's 1-2-3, 80). Usually, however, these authors and the others described such illustrative situations by being more hypothetical, "Imagine you're required to" or "Assume that you boss has asked you to." The most striking difference among the texts is the degree to which they use persuasive strategies. WordPerfect Workbook briefly notes in the introduction "the power and flexibility of WordPerfect" but spends few words after that to extol the virtues of the program. 1-2-3 Tutorial does very little verbally, but it does use four-color photographs to illustrate the variety of businesses that are helped by using 1-2-3. Neither of these texts bothers to sell the reader on the qualifications authors have for writing the manuals. Presumably, the fact that the book is published by the manufacturer is testimony enough to its accuracy or usefulness. On the other hand, the authors of Using WordPerfect and The ABC's of 1-2-3 frequently tout the virtues of both the software and their own books. ABC's devotes three pages to describing the benefits of using 1-2-3 and three paragraphs to what this book can do for the reader. "Written iri nontechnical, everyday English, it introduces 1-2-3 simply and practically in a series of 67 lessons" (xvii). It also claims to be better than the Lotus documentation at explaining how to apply the program. The 83

PAGE 92

authors also declare their own credentials for being experts on WordPerfect, thus persuading the reader to trust them. Of all the authors, the authors of Using WordPerfect take the strongest marketing approach in extolling their subject's benefits. The first chapter starts with a description and explanation of WordPerfect's popularity, including the claim that "WordPerfect 511 heralded a 'quantum' leap forward for a product already enjoying ever increasing popularity worldwide" (14). Frequently, when introducing a feature, the writers speak of its benefits, not just its attributes. Throughout the text comments like the following appeal to the reader's enthusiasm: By freeing you from much writing drudgery, WordPerfect gives you more time to be creative or to rethink your work (41). WordPerfect gives you a quick way to move the cursor ( 48) with WordPerfect, you can be flex'ible about printing (53). WordPerfect's Speller and Thesaurus provide you with two valuable tools for increasing efficiency and accuracy as a writer(229). The qualifications of the writers are also given more space than in the other books. By offering short professional biographies of all thirteen contributing writers, the author in charge establishes their credentials and persuades the reader to trust their 84

PAGE 93

advice and knowledge. He also strengthens their credibility with an anecdote about how he discovered their WordPerfect expertise through eight months of monitoring the WordPerfect forum on Compuserve. The fact that both The ABC's of 1-2-3 and Using WordPerfect give background information about the authors is a characteristic these books share with most books outside the field of software documentation. It makes the books look more like "real" publications and not just corporate writings. Situationality All of the texts manage the discourse situation. They direct the reader's progress carefully from beginning steps to more advanced lessons, taking the readers' lack of knowledge (the problem) and deproblematizing it (de Beaugrande and Dressler). They guide the reader's attention from page to keyboard to screen with instructions to type in data, enter commands, or note what is displayed. Each text, using from one sentence to several paragraphs, explains who should read the book, thus managing their intended audience; and dictates how the book should be read: what must be read, what can be skipped, and in what order the materiai should be covered. (Using WordPerfect, 3-4; WordPerfect Workbook, 85

PAGE 94

1-2; The ABC's of 1-2-3, xvii-xxii; 1-2-3 Tutorial, Preface) The texts vary in the way in which they monitor the situation, that is the degree to which they let the author's beliefs about learning the software mediate how they present the situation. Neither WordPerfect Workbook nor 1-2-3 Tutorial discuss whether or not the software is difficult to learn or whether their text is easy to follow, although the workbook author does say the text is designed "to help you understand how to create and format a variety of documents" (1, my italics). Both books do suggest that novices use the on-line tutorial before they read the text. The authors of Using WordPerfect do not claim their text to be more helpful than the documentation from WordPerfect corporation; instead they view it as an "excellent complement" (3). They not only encourage all readers to use the on-line tutorial, even those familiar with WordPerfect 4.2, but they give directions for using it and an overview of its contents (33). The authors of The ABC's of 1-2-3 are not so gracious. They frankly admit that 1-2-3 is complex; that the manuals and on-screen lessons are "excellent reference tools" but that they take too long for learning and the on-screen material allows no experimentation. They then explain why their book is better (xxii) 86

PAGE 95

Informativity While every discourse has some degree of informativity, it is the essential characteristic-of reference/informative (Kinneavy 1971) or instrumental (Beale 1987) or didactic (De Beaugrande 1980), the categories that software documentation belongs under. However, discourse that is too informative, containing too much information will be harder for readers to comprehend and assimilate. Ratio of Given Information to New. At the sentence level, we can look at the pattern of givenjnew information as it's carried forward from one sentence to the next. The samples paragraphs used for analyzing coherence show that the authors do follow the expected pattern. In looking at the texts to see the proportion of new information, I noticed that some texts use terminology specific to the software more frequently than others do. Passages that usea larger number of these terms could be said to have a higher density of new information. Passages that used fewer new terms would be easier to understand. I selected four short passages, 200 words from each text (see Appendix c for samples), all from the beginning of a lesson. I counted all words considered new and specific to the learning task, including the name of the 87

PAGE 96

software. I counted each new word used and the number of times these were used. Table 3.1 shows the results. Table 3.1. Density of New Words in Each Text. NUMBER OF TEXT NEW WORDS TIMES USED -------------------------------------WordPerfect Workbook 13 (6.5%) 28 (14.0%) Using WordPerfect 12 (6.0%) 19 ( 9.5%) 1-2-3 Tutorial 12 (6.0%) 23 (11.5%) The ABC's of 1-2-3 6 (3.0%) 17 ( 8.5%) Based on this short sample, both of the secondary texts were slightly less dense, using new words less frequently (9.5 and 8.5 per cent of the words) than did the primary texts (14.0 and 11.5 percent of the words). Only The ABC's of 1-2-3 used a fewer number of unique new words. It appears as though the other texts may have reinforced the new words by repeating them, when, in fact, they repeated only four or five words new words, and used the others but once. Comprehensiveness. Another measure of a text's informativity is its comprehensiveness: how much information is presented. To give a rough estimate of the sheer bulk of information, I counted the text pages and index columns. Granted, these are not definitive, 88

PAGE 97

since the number of words on a page for a given text will vary by page size and type size, but the figures are a starting point. For the documentation from each manufacturer, I counted pages and index columns for the workbook and tutorial alone, and then totaled these with the other written documentation supplied. The pages are counted from the beginning of arabic numbers. The results are shown in Table 3.2. Table 3.2. Comprehensiveness as Measured in Text Pages and Index Columns. TEXT WordPerfect Workbook Reference Total Using WordPerfect Lotus 1-2-3 Tutorial Getting Started Reference Total The ABC's of 1-2-3 TEXT INDEX :fl of Pages :fl of Columns 398 15.00 483 23.25 881 38.25 850 48.00 162 16.00 55 4.50 327 29.25 544 49.75 332 16.00 By sheer number of pages, the single volume from Que comes close to matching the two volumes from WordPerfect, and it has a larger index. The Sybex book, The ABC's of 1-2-3, does not equal the total pages for the volumes from Lotus 1-2-3, but it does exceed the number of pages 89

PAGE 98

in the tutorial. Its index, however, appears less comprehensive. Arrangement. Another factor in informativity is the arrangement of the content. All four texts are ordered around pragmatic considerations, how the readers use the software rather than semantic descriptions of the software. Tasks for "Getting Started" (installing the program, turning it on) are either presented first or pointed to as the first step. Thereafter all four texts progress from easy skills to more advanced. At first glance, the fact that WordPerfect Workbook is ordered by type of document, appears to be a descriptive approach. The order is actually functional, if somewhat limited, since the author has focused on tasks needed to create each document. It would be hard to find out how to do a specific task that's common to a number of documents if the authors hadn't included at the end of the book a cross-reference list by feature/ function, e.g., "Centering Text." As for keeping types of information distinct and separate, Using WordPerfect clearly separates previews from the remaining chapter, but it mixes descriptive, background information with procedural steps. The ABC's of 1-2-3 introduces chapters with background, conceptual information followed by a distinct procedural section, always titled "How to" do something. The introduction to 90

PAGE 99

each chapter of 1-2-3 Tutorial is on a separate page, but the short background material for the lessons blends right into the step-by-step instructions, as it also does in WordPerfect Workbook. since the manufacturers provide separate volumes for reference and tutorial material, they differentiate between advanced and novice users. However, this arrangement does not accommodate learners who are on a fast track. The tutorials proceed at the same pace, regardless of the learner's experience with word processing or spreadsheets. This steadfast pacing is also true for The ABC's of 1-2-3. Using WordPerfect, however,-provides an alternative fast track, called 11Quick Start,11 at the end of each of the first six chapters. This material accommodates the reader who is impatient with lengthy explanations and wants to get down to work. Novice readers can aiso use 11Quick Start11 to reinforce what they learned earlier in the chapter. Intentionality and Acceptability Who are the authors-and what are their intentions in writing? Who are the readers and what roles do the authors ask them accept? Each text handles the relationship between author and reader somewhat differently. Generally the relationship is established early in the text, often with explicit comments about the 91

PAGE 100

identity of the authors and readers. Readers are usually classified by level of expertise. WordPerfect Workbook: The text does not name an author, either on the cover or on the first title page. The reader can only assume, that since the book came from the manufacturer, the author is one or more people working for WordPerfect Corporation. Nonetheless, these. authors address the reader directly as "you" and establish a helper-to-learner relationship with the very first sentence of the introduction: "The WordPerfect Workbook is designed to help you understand how to create and format a variety of documents" (1). Aside from being users who need help, the readers are identified as people who are already familiar with computers and processing (if they're not, they are directed to try the on-line tutorial) or who are already familiar with WordPerfect (presumably an earlier version) and eligible to skip the "Fundamentals" section. Readers are sometimes asked to play two roles simultaneously. At the beginning of some lessons, the author addresses the readers as though they were playing the role of workers in an imaginary office. For example, Lesson 6 begins, "The second draft of the reservation letter has returned with no additional editing marks." In the next sentence the author could be acting as either the instructor again or as a co-worker pointing out what 92

PAGE 101

the student/worker needs to do next: "However, the date at the top of the letter and the initials below the signature still need to be included." In the third sentence the author reverts less ambiguously to the role of instructor for WordPerfect and directs the reader to be the student again. This shift in roles may or may not be disconcerting to readers, who could decide to pick one role and ignore the other or just accept the occasional play acting. 1-2-3 Tutorial: The text from Lotus does not name the author either (although it does list the photographer and the illustrator on the page facing the preface). Like the corporate authors of WordPerfect Workbook, the authors of Tutorial also address readers directly as "you" in the first sentence of the preface. They do not explicitly define the relationship to the reader, perhaps because the title of the book establishes it as tutorpupil. They do mention lessons and the fact that the reader "must learn a few basic concepts and master a few basic skills" (1). The book "is designed-for people who are unfamiliar with computers or 1-2-3" (Preface). The ABC's of 1-2-3: The Sybex text does name the authors, two of them--Chris Gilbert and Laurie Williams-and even describes their background, briefly and without telling who's who: "One with the technical background to teach corporate users, the other a novice who had never 93

PAGE 102

before used the program" (xvii). The authors further declare their humanity by each dedicating the book and by acknowledging other people who contributed their time and expertise. The authors are very clear about who they intend their readers to be: people who have "never used Lotus 1-2-3 before and want to learn how," even if they've never operated a computer (xvii). They may also be people who are dissatisfied with the documentation from Lotus, as the authors are (xxii). Gilbert and Williams promise to speak their language by writing in "nontechnical, everyday English." As noted earlier, the "ABC" title reinforces the impression that this is a simple book for beginners. While the text presents a teaching situation, the authors narrow the distance between teacher and pupil by using a sympathetic tone of voice, that their readers might have difficulty or make For example, Lessons 9 and 11 are titled "Help! What Do I Do Next?" and "Oh No! How Do I UNDO a Mistake?" Occasionally the authors use the same technique as the authors of WordPerfect Workbook, suddenly casting the readerjpupil as a worker in an imaginary work situation. Lesson 18, for example, begins with the statement, "A few seconds ago, a colleague walked into your office with revised figures" (80). More often, however, the authors are aware that this is another role and address the 94

PAGE 103

reader from the original context of tutor-pupil, setting the stage instead by asking the reader to "assume that you are preparing a report" (186) or "suppose that you wanted to determine how many salespeople were high sellers" (260). Using WordPerfect: I've saved this text for last because it develops the relationship between authors and readers more elaborately than the other texts. Not only does the text name all the authors (thirteen of them) and give short biographies of their professional background, but it claims that the author's expertise and collaboration is the very reason for writing the book. As word-processing software continues to evolve rapidly and becomes feature-laden, complex, and increasingly .useful for a diversity of users, the need for expertise across a range of experience is clear. If you add the demand for expertise to the need for a useful guide to the new version as soon as possible, you can see why a collaboration of WordPerfect experts on Using WordPerfect 5 was an optimal solution (2). Their expertise includes college teaching, programming, training, computer consulting, writing, advertising, accounting, and law. They each contribute one or more chapters based on their personal experience with the system. A second, one-sentence biography of the writer precedes each chapter. Readers don't have a chance to forget who is addressing them! 95

PAGE 104

The lead writer and editor, Charles o. Stewart, includes a dedication and acknowledges the help of people at the publishing house, production people as well editors, and at WordPerfect Corporation. The authors claim the text has something for readers at every level of WordPerfect experience. Beginners are directed to use the WordPerfect on-line tutorial first, but thereafter the text's tutorials and "clear instructions will help [them) master version 5 quickly" (3). Users who know an earlier version of WordPerfect "will make a smooth transition from 4. 2 to 5." And proficient users "will want to use [the] book as a desktop reference." Like the authors of The ABC's of 1-2-3, Stewart et al. establish a friendly relationship between teachers and pupils, using the first person plural ("Let's experiment with the sample text") and reminding readers of the progress they're making ("You see how easy it is to move the cursor horizontally across a line of text") (47). The authors frequently draw upon their.experience to give examples and tips for applying WordPerfect's features to the readers own tasks. This ability further strengthens the bond between the two. It also gives WordPerfect users a little extra help with the writing process, tying their. increasing knowledge of word processing into the global purpose of communicating. 96

PAGE 105

This help is particularly evident in the chapters on creating and editing documents and in the chapter on producing publications. The authors' intentions toward readers are also established through the choice of grammatical style. I've attempted to analyze style according to Gibson's suggestions for developing a serious style without being stuffy. I've examined excerpts from the four texts (the same samples used to evaluate the density of new material, shown in Appendix B). Table 3.3 shows the results using an abbreviated form of Gibson's "Style Machine" (136). To begin with, all of the texts use two conventions of software documentation that immediately place them in the "sweet" category. one is addressing the reader directly as "you, i establishing intimacy; the other is a variety of discourse punctuation, particularly boldface for commands and parentheses for names of keys. Based on numbers of syllables, the texts for WordPerfect tend to be tough, whereas the texts for Lotus 1-2-3 tend to be sweet. The ABC's of 1-2-3 falls into the stuffy category when it uses too few people as subjects; and the Que book is stuffy about its use of finite verbs. For the remainder of the criteria, the texts fall short of Gibson's goal of_being serious without being stuffy. 97

PAGE 106

Table 3.3. Analysis of Texts Using Gibson's Style Machine. CRITERIA* # of monosyllabic words (66.6% of total) # of words with 3 or more syllables (20%) # of subjects that are people (50%) number of finite verbs (10% of total words) number of passive verbs (limited) # of noun adjuncts (limited) punctuation (except comma and semi-colon) (varied) parentheses. bold question mark colon subject interrupted before verb (none) # of contractions (for variety) # of fragments (for variety) WORDPERFECT LOTUS 1-2-3 Wk Bk Que Bk Tutor ABC's 148 146 127 127 74.0% 78.0% 63.5% 63.5% 16 19 31 21 8.0% 9.5% 15.5% 10.5% 11 12 18 8 58.0% 66.6% 78.3% 30.7% 23 18 28 26 11.5% 9.0% 14.0% 13.0% 0 2 0 1 6 6 1 0 6 2 0 0 4 0 6 0 0 0 0 3 0 0 1 1 0 1 0 1 0 0 0 1 0 0 0 0 These criteria are for a voice that's serious without being stuffy. Use of too many devices equals too sweet (or too tough) a voice. 98

PAGE 107

Instead they are in the sweet andjor tough category. Perhaps Gibson's goal is not the ideal for software documentation; perhaps his style machine needs to be brought up to date and tested on longer and more varied samples to find suitable criteria for software documentation. This analysis of cognitive and rhetorical factors in the four texts has been very broad based, looking at the whole texts in general and at short passages in particular. It wasn't my intention to come up with a quantitative measure of their superiority or inferiority, but only to identify those factors that might indicate why the secondary texts from Que and Sybex enjoy such popularity. Nonetheless, it's possible to compare the texts subjectively, on a scale from to see how they manifest the factors Tables 3.4 and 3.5 show the relative standing of each manual. 99

PAGE 108

Table 3.4. Comparison of Primary and Secondary Texts for Cognitive Factors. WORDPERFECT LOTUS 1-2-3 FACTOR Wk Bk Que Bk Tutor ABC's ---------------------------------------------Type I Processing: 5 3 4 5 Encourages immediate recall and use through rehearsal (repeated practice) and emphasis on detail (coordinate lists) Type II Processing: 2 5 4 4 Encourages long-term conceptual learning and problem solving through analogies, familiar-to-formula presentation, and elaboration. Use of Schemas: Invokes existing 4 .5 4 5 knowledge through real tasks, analogy. Builds new schemas using 4 5 5 5 agent-action constructs at both the section and sentence level and through practice. Text Processing: Provides clear macro-3 5 4 5 structure, through previews, heading levels, and running text (memory for gist). Provides coherence at 5 4 3 2 sentence level. TOTAL POINTS 20 22 20 21 100

PAGE 109

Table 3.5. Comparison of Primary and Secondary Texts for Rhetorical Factors. WORDPERFECT LOTUS 1-2-3 FACTOR Wk Bk Que Bk Tutor ABC's ------------------------------------------------Intertextuality Shares physical character-2 5 3 5 istics of other "books" (size, binding, front matter). overlaps purposes of other 2 5 3 5 texts (persuasive, dramatic). Situationality Monitors the situation. 3 5 3 5 Manages the situation. 5 4 5 4 Informativity Balances givenjnew. 2 4 3 5 Comprehensive compared to total primary documentation. 5 5 5 3 compared to Workbook or Tutorial. 3 5 3 5 Content organized pragmatically. 4 5 5 5 separates conceptual and procedural. 4 3 4 5 accomodates novice and expert. 5 5 4 3 Intentionality and Acceptability 2 5 3 4 Strength of connection between writer and reader. TOTAL POINTS 35 46 38 44 101

PAGE 110

A pattern does emerge concerning similarities and differences regarding the cognitive and rhetorical factors. The greatest difference is between the texts from WordPerfect Corporation and Que. The Lotus texts resemble each other more closely, with the tutorial from Lotus 1-2-3 being more like WordPerfect Workbook and The ABC's of 1-2-3 being more like the Que book, Using WordPerfect. In other words, the four texts form a continuum of similarity and difference: WordPerfect 1-2-3 The ABC's Using Workbook Tutorial of 1-2-3 WordPerfect If the continuum were a measure of quality, from least to most, the relative placement of the Sybex book and the Que book would agree with the sales charts. 102

PAGE 111

CHAPTER 4 DISCUSSION OF SIMILARITIES AND DIFFERENCES Given that many readers denounce the documentation from manufacturers as impossible to learn from (Anthony 1989), one would expect to find that the primary texts are poor in most respects. Instead I found that the workbook from WordPerfect and the tutorial from Lotus, like the secondary texts from Que and Sybex, take into consideration most of the cognitive factors that affect learning. They encourage practice and interaction with the computer; separate complex activities into clear, step-by-step instructions; provide concrete analogies and advance organizers; invoke existing work schemas; and use agent-action constructs. at both heading level and sentence level. All of the texts use hierarchical headings to help readers build a sense of macrostructure and all strive for coherence at the macroprocessing level, although coherence is stronger in the books for word processing than in the spreadsheet texts. Where the secondary te.xts differ from the primary texts, for cognitive factors, is in the degree of conceptual, background information given--a difference

PAGE 112

that encourages long-term memoryand problem solving (Type II processing) rather than short-term recall for immediate use (Type I processing). This difference in conceptual information may be accounted for by a striking rhetorical difference between the two texts: the secondary texts succeed in building a much stronger connection between the authors and the readers. They do so with three characteristics that are either absent from I or marginally included in the primary texts. The authors of the Que and Sybex books o Share their identity with the readers. o Provide a richer context through more examples for applying the software. o Use persuasive, marketing techniques to ease readers' anxieties and to remind them of the software's benefits. Because the identify themselves, by name, to the readers, readers know that real people are addressing them. The readers also know from the authors' biographies or statements about themselves that the authors understand the problems readers face on the job or in a horne office. one author of The ABC's of 1-2-3 is a novice user and can be personally sympathetic to the readers' difficulties in learning. The other author 104

PAGE 113

works in corporate training and knows not only how to teach but how people work in corporations and how they are likely to use Lotus 1-2-3. The authors of Using WordPerfect have even stronger ties to their audience since they, like the readers, use the the software for writing in a variety of professional settings. And since they come from a variety of professions, they can identify more closely with many types of readers. But the authors do more than just state their expertise. They draw upon that expertise to give realistic examples and advice about how the software can solve problems in writing and spreadsheet tasks. They enrich the context of learning more than the authors of the primary texts do; the Que authors even go beyond word processing to discuss the writing process itself. The ability to offer situational examples is a real asset. According to a study by Charney and Reder (cited by Shriver et al. 1986) which compared the effectiveness o.f analogies, instantiation examples, and situations, "situation examples are the mostuseful for skill learning" (88). The writers of the primary texts never do identify themselves. Instead they hide behind the impersonal mask of the corporation, where readers cannot connect with them. Not knowing the name of the authors may not be 105

PAGE 114

significant to scientists or engineers (or the at the software corporations), but authors' names are remembered by people in the humanities (Ramsey 1980)--the non-technical people who need to learn about computers. Since we don't know the authors of the primary texts, we also don't know if their professional backgrounds are similar to the other authors' backgrounds. Even if the. backgrounds are similar, the corporate authors are not exploiting that experience to connect with their readers .. While they do provide readers with sample tasks to work on, they emphasize the functionality of the software rather than the application of skills. Concern for the functionality of the software is, of course, the main concern of the programmers and designers--the very people with whom the writer must work. The pattern of identification that is emerging reinforces my original hypothesis that the process of disseminating technical information requires several steps--or locks--to reach a less technical audience. 106

PAGE 115

Here we're focusing on just two levels: Primary Text Authors identified with impersonal corporation Work with software engineers/programmers, who are interested in things Emphasis on functionality and features Secondary Text Authors identified as individuals with names .Work primarily with nontechnical people, who are interested in people Emphasis on application and benefits The difference between an interest in things and an interest in people is noted in research on personality types (Sides 1989). The dichotomy represented here is not new. What's interesting, though, is that information is transferred from one culture to another. The authors of the secondary texts use the original documentation to learn from; and they use their process of plus their experience-based knowledge of their audiences' needs to produce the popular text. The split between the cultures of the primary and secondary texts resembles the split between manufacturing and marketing in business; and, like marketing people, the authors of the secondary text are not afraid to use persuasive language. Perhaps their readers need, and want, more motivational techniques to encourage learning. In particular, non-technical people who are highly 107

PAGE 116

anxious about computers (or adults who are nervous about learning) can benefit from information that reassures them and reduces tension. These emotional needs take precedence over the need to learn logical material (Hand 1982). In addition, reminding readers of the benefits of of the software helps them apply knowledge of the software to the writing and spreadsheet tasks they want to accomplish. Learning WordPerfect or Lotus 1-2-3 does not become an end in itself. To some extent, building a relationship with readers may seem like an extension of audience analysis: consider the readers' needs. I think it goes deeper. It's not enough, for instance, to consider just cognitive factors and the reader's ability to process text. For example, in an experiment by three pairs of linguists, composition instructors, and editors from Time-Life, each pair revised passages from a history text book to improve it (Duin 1989). The linguists and composition instructors improved the structure and coherence; the editors revised for both those factors btit also "radically'' changed the content to suit the "knowledge, attitudes, and needs" (100) of a high school audience. Of the six hundred high school.students who participated, those who read the original version and the versions revised by the linguists and compositions instructors learned and recalled about 20% of the material. Those who read the 108'

PAGE 117

version revised by the Time-Life editors recalled 60%. The editors' understanding of what the audience needed made the dramatic difference. How do technical writers acquire this kind of knowledge and understanding of an audience? The easiest way is to be a member of the audience or "discourse community" that they're writing for. As Rubin observes in his article on social cognition (1984), "it's difficult to write in a genre for which one lacks corresponding audience constructs" (223). Research in personality types also shows that people of a given personality type will have natural affinities for or aversion to certain other types. For example, engineers tend toward thinking judgments and may easily conflict with writers who tend toward feeling judgment (Sides 1989). The authors of the seconda.ry texts, especially the Que books, are farther removed from a computer science environment and more closely allied to the environment of their users. They have experiential knowledge of their audience's needs and can "speak their language." For writers who have an assignment where they do not already share an identity w.i th their audience, building a sincere relationship can take more work. Imagining the audience may not be enough; writers must actively get to know that audience. They need to interview, shadow, read 109

PAGE 118

about, take out to lunch, attend the same conferences as, and generally start to think like the people they want to reach. This is the advice that all good advertising and sales people already know about selling to their markets (Ogilvy 1983). It's probably what the Time-Life editors know about reaching mass markets. It means spending time with the people we're writing for. Floreak took this approach whendeveloping "brochures" on child care for functionally illiterate adults. Through repeated, extensive in-home interviews and usability testsof initial materials, the research group altered their ideas about what approach to take. Instead of the traditional brochure, the final product was a series of posters with photographs, line drawings and simplified text, a format that appealed to this audience (Floreak 1989). While the quality of relationship between writer reader is one of the chief between the primary and secondary texts, it is not the only one. Several other differences raise questions suitable for further research. Comprehensiveness. The Que book incorporates more information in one volume--background information, quick tutorial, and a substantial index--than any of the other texts do. Is it effective to appeal to the needs of many different readers in one text, or should we write for one audience and let the buyer decide? 110

PAGE 119

Ratio of Given/New Material. Can we accurately measure the ratio of new to given material in an entire instructional text? And is there an optimum ratio that documentation writers should strive for? Intertextuality. How significant is it to use persuasive and motivational language? Does mentioning benefits and easing readers' anxieties increase learning of technical material? And is this approach acceptable to all or most readers? Reader Preferences. Despite a survey (Penrose and Seiford 1988) of members of microcomputing groups--a biased population--do readers really want three-ring notebooks for documentation? or do they prefer texts that resemble other reading material? Do we need to know more about the people who buy the secondary documentation: What their backgrounds are? Why they bought the book? How useful they really found the book? Learning Styles. One chapter in the Que book, the one written by a lawyer and concerned about legal briefs, did not enumerate procedural information. The procedures were still there, but they were embedded as sentences in paragraphs. Do some readers prefer to read material that is not heavily formatted? Should documenters of vertical market software, e.g., programs directed at lawyers, 111

PAGE 120

dentists, retailers, or records managers, consider the specific learning styles of their audience? Author's Identity. The Que and the Sybex books are not the only secondary texts that identify the author. Virtually every manual available in book stores lists the author's name. Why then does it seem like normal practice for manufacturers to omit it from their manuals? Is this really significant? Should technical writers be pushing for by-lines? Would identifying the authors humanize technical writing? Would giving technical writers credit elevate them to the professional status that writers and editors have in traditional publishing houses? While research in these areas might give new direction to writers of software documentation, writers don't have to wait to change.their approach. By thoughtfully studying examples of secondary texts that have proven their success in the marketplace, writers, and corporations that employ writers, can find useful strategies on which to model their own documentation. 112

PAGE 121

APPENDIX A. SAMPLES OF FOUR TEXTS USED FOR ANALYSIS 1. WordPerfect Workbook 2. Using WordPerfect 3. 1-2-3 Tutorial 4. The ABC's of 1-2-3

PAGE 122

--------Lesson 10: Letter 2-Final Draft Inserting the Date Changing the Page Numbering Style Figure A.1a. The second draft of the Swiss America letter has been returned with a note to alphabetize the two lists of music boxes and change the style of page numbering. The current date should also be added to the lener. Let's begin by retrieving the letter and adding the date. 1 Press List Files (F5) and then press Enter ro display the list of files on your disk. 2 Move the cursor to the "Musicbox" filename, and then select Retrieve (I) to retrieve the file. 3 Press Date/Outline (Shift-F5) and select Date Text (I) to insen the current date. 4 Press Enter twice to add extra spacing. The style of page numbering needs to be changed to a more standard form that includes the receiver's name and the current date with the page number: euut.iful bna-r A.lwaya rant.Y Lltt le n-r Girl Ju11 a SO"'J bett Paralle so-hare, so-1\cJw Joplll'l San FI'81'1C1.CO Rlqhta Mapp&naaa Grecun Holiday Lolly llhrar lnu ... C'o,.nh19an Taha It WO\IId be qraatly appraclat .. d II you &::ould II'IIP an aaaort-nl of approtely !t uaiC'"DOiaiJ to aAc:h of our rapraaant.at.JY&& by U1a laat -k U\ Novebr. Our corporate aecoul'ltant viii bP In toueh wltl'l you to 1,1p an a&::eount Vltl'lu U'1 wak. II tl'lar a& ant lor I!IUI.IC: tooara, tl'll'llp.erenc:la&, ate., plaaaa Plill tne .. to th .. ec:ou"t Tl'l hllowanqo h eurrM lut ol F"'fiDnal "'rllf'tlnq reprell'llt.llt.IYIK: !oU Wet."tr cuc:h HW &.tlnt.e, c. I lO n UOI) )!o-:nn While WordPerfect's automatic page numbering prints a page number. you need to create a header if you want to include text with page numbering. First sample page from WordPerfect Workbook, reduced 80%. 114

PAGE 123

Erasing a Code A PAGE NUMBERING cooo Figure A.lb. Before creating the header. however. you should first erase the old page numbering code 5 Press Page Down (PgDn) to move the cursor to the very beginning of the second page. 6 Press Reveal Codes (Ait-F3) to display the codes at the beginning of the second page. ..... uf"l ur-u a .,. Crt.rnt- rantaar t.lUh rloo.r-r CHI Juat asant; Paraoa Soatvhera. SO..I'IVV Joplin San Fri!JI"II:U.CV Jfl91'1tl Mappln.aa Cracum MoiiOer Ia:' I a J Ll'l I" Pol I" jrtJitl IHPGI II !lllii!F II Cru-riNAt.l AJwa)'IMMtl Fantaar(l'llltl LU't.h rlow.r G1rl1MIItl Juu a SOrlt(MRtj aatar ParadeiM8t) s-w,..ra. SC..'-IIIIfilt I JopllniM"tl Because page formats need to be at the very beginning of the page (before any text) for the feature to work correctly. using Page Up and Page Down to move from page to page will always place the cursor is in the correct position for adding a page format. Instead of deleting the page numbering code in the Reveal Codes screen, try erasing the code from the document screen. 7 Place the cursor on the page numbering code (if it is not already there). 8 Press Reveal Codes (Ait-F3) to display the full document screen. 9 Press Delete (Dell to erase the page numbering code :.ESSON 10 .aJ Second sample page from WordPerfect Workbook, reduced 80%. 115

PAGE 124

138 USING WORDPERFECf 5 Printing a Block To print a block of text, you first highlight it and then issue the Print command. WordPerfect asks you to confinn that you want to print the highlighted block. WP 5 To print the first paragraph of the sample memo, follow these steps: 1. Move the cursor to the beginning of the first paragraph of the memo. 2. Press Block (Ait-F4, or F12) to tum on the Block feature. 3. Move the cursor to the end of the paragraph. 4. Press Print (Shift-f7). The screen displays the following message: Print block? CYIN) No 5. Press Yfor Yes to confinn that you want to print the highlighted block. The block wiU print on the currently selected printer. This Quick Start introduces you to the basics of using the Block command. Be sure to read through the chapter to learn more about the techniques illustrated here. The Block command is easy to learn. Once you've mastered it, you are on your way to using WordPerfect's powerful editing capabilities. Summary The Block command is pan of a process. In this chapter, you've learned to use that command to highlight text on which you want to perform some operation. Highlighting a block is .the first step in all the Block operations. The basic procedure is always the same: I. Move the cursor to the beginning of the block of text you want to highlight. 2. Press Block (Ait-F4, or Fl2). 3. Move the cursor to the end of the text you want to highlight. After you've highlighted a block of text, you can move it, copy it, delete it, append it to another file, save it, or print it. You also can change the appearance of a block of text. You can make the text bold, underline it, make it larger or smaller, change it to uppercase or lowercase, or center it. Working in tandem with many WordPerfect commands, the Block command helps you make important changes to your document quickly and easily. Figure A.2a. First sample page from Using WordPerfect, reduced 92%. 116

PAGE 125

WP 5 5 Formatting and Enhancing Text Schuyler Lininger, Jr., an Oreyon chiropractor and owner of HeaJtbNotes PUblications, uses desktop publishing to produce fliers, brochures, and newsletters for tbe beaJtb food industry I WordPerfect offers many useful tools that delight both novices and experienced word-processing users. If you have been using a typewriter, you will enjoy the way WordPerfect handles the mundane chores of setting margins and tabs; centering, justifying, underlining, and boldfacing text; indenting text; and hyphenating words. If you are an old hand with word processors but new to WordPerfect, you will be impressed with how simply and logically WordPerfect fonnats and enhances text If you are an experienced user of WordPerfect 4 .2, you will appreciate the many enhancements included in WordPerfect 5 ; these enhancements make your work even easier. In this chapter, you will learn how to enhance text you have already entered. You also will learn how to fonnat lines and paragraphs so that they appear as you want them when printed. Text enhancements described in this chapter include the following: Using left and right margins (including using margin release) and indenting text from the left and from both margins Using various types of tabs : left, right, center, decimal, and tabs with dot leaders Fonnatting text to make it centered, flush right or right-justified Changing line spacing and adjusting the height of each line (leading) Manually or automatically inserting hyphens into text You also willleam how to take full advantage of your printer's capabilities, including the following: 139' Figure A.2b. Second sample page from Using WordPerfect, reduced 92%. 117

PAGE 126

18 Figure A.3a. i I \ I I The illustration above describes the process you will go through In this chapter. You begin with a handwritten page of information and questions the owners have about their finances and organize this information in a 1-2-3 worksheet. Then you use the worksheet to calculate the store's projected income. Finally, you create two graphs illustrating the infor mation in your worksheet. Tutorial First sample page from 1-2-3 Tutorial, reduced 85%. 118

PAGE 127

.................................................................................. Lesson 1 New Keys to locale: CAP LOCK BACKSPACE Beginning the Income Worksheet When you begin a worksheet. you must consider how you want to arrange the information that will appear in it. You can use labels to organize the numbers that appear In the columns and rows of the worksheet. In a sense. these labels represent the structure for the numbers and are a logical place to begin. In this less;m. you will learn how to enter labels in a work sheet, correct typing errors. save a worksheet, and erase a worksheet. Start 1 so that you have a blfnk worksheet on the screen Entering Text Begin by giving your worksheet a title in the upper left cor ner. Note that you can press CAPS LOCK once to type upper case letters and a second time to return to lowercase. Move to cell A 1 Type the first letter in the worksheet title, I Notice two things that happen. First. the letter I appears on the second line of the control panel at the cursor. Second. the mode indicator changes from READY to LABEL. Mode Indicator When you make an entry, the mode indicator changes in response to the first character you type. A letter changes 1-2-3 from READY mode to LABEL mode. indicating that you are entering text. A number changes 1-2-3 to a mode called VALUE. indicating that you are entering numbers or for mulas. You will learn more about LABEL and VALUE. as well as other modes. in later lessons. Finish typing: INCOME PROJECTION 1986: Jetson's Camera Store but do not press RETUltN Correcting Mistakes Check the second line of the control panel to make sure that you have not made a mistake. If you have. correct it before you press RETURN by pressing BACKSPACE. retyping the deleted portion. then pressing RETURN. BACKSPACE erases characters to the left of the cursor one at a time. If you notice an error after you press RETURN. correct it by typing a new entry in that cell and entering it to replace the old one. figure A.3b. Press RETURN Building a 1 Worksheet Second sample page from 1-2-3 Tutorial, reduced 85%. 119 19

PAGE 128

42 Part 2: Building a Worksheet /.cntm /0 LESSON 10 Correcting l\fistakes in a Cell FEATURING The EDIT (F2) function key In 1-2-3 you can often do one thing several ways, such as correcting a mistake. Until now, you would correct an error by using the Back space or Escape key before entering on the worksheet or by overwrit ing an entry already on the worksheet. EDIT (F2) allows you to correct a single error more easily. For example, if you type BUDET on the control panel instead of BUDGET, you would have to erase the T and E and type in GET before you entered it on the worksheet. Or, if it were already on the worksheet, you would have to type the entire word over and reenter it. Instead, using the EDIT mode, you simply insert the G where it belongs. The F2 key enables you to make corrections any time you notice a mistake. If the error has not been entered on the worksheet, you can press F2 and correct it while it is still on the control panel. Once the entry is on the worksheet, you simply move the pointer to the cell that needs correcting, press F2, and the entry is pulled up to the control panel for editing. In effect, all errors, whether they are on the con trol panel or already entered on the worksheet, are corrected on the control panel. At this stage, forgetting to enter a label prefiX and making an incor rect entry are the most common errors. The following instructions Figure A.4a. First sample page from The ABC's of 1-2-3, reduced 95%. 120

PAGE 129

Correcting Mistakes 43 show you how to correct these mistakes, using the EDIT mode to enter and delete characters. How to Correct Errors wirh the EDIT (F2) Function Key 1. To practice on a new screen, tap the PgDn key on the right side of the keyboard. This will bring up rows 21 through 40, where you can enter mistakes in order to learn how to correct them If You Forget to Enter a Lahel-Prefix Character 2. Press the Caps Lock key. CAPS is displayed. In the cell where the pointer currently resides, A35, type: 1991 BUDGET Do not type a label-prefiX character. Notice that the mode indicator changes to VALUE, not LABEL. 3. Press Enter. 1-2-3 beeps, your entry remains on the control panel, and the EDIT mode is automatically invoked because, although it doesn't recognize all errors, 1-2-3 knows when you forget to enter a label prefix if the label begins with any one of the following characters and contains letters: 0123456789+.(@$ An entry beginning with one of these characters is normally interpreted as a nwnber or a mathematical formula. This is called a value. However, because there are letters in the entry, 1-2-3 recognizes the error and knows that you intended to enter a label. 4. When you are in the EDIT mode, the pointer-movement keys respond differently. The Right Arrow and Left Arrow keys now move a small cursor along the second line of the control panel. Move the cursor to the flrst 1 in 1991 BUDGET and .type a single apostrophe. Figure A.4b. Second sample page from The ABC's of 1-2-3, reduced 95%. 121

PAGE 130

B. TEXTS USED FOR ANALYZING COHERENCE The underlined phrases are given information; nonunderlined are new information. The numbers next to each sentepce refer to the sentence hierarchy, following Christensen's approach (1967). From WordPerfect Workbook, page 41: (A) 1 Now that you have been introduced to a few basic features of WordPerfect, it would be a good idea to explore the resources available for getting the help you may need to solve a problem, answer a question,or find out more about WordPerfect. (B) 2 One of the most valuable tools for (C) (D) (E) (F) helping you out of an immediate problem is the cancel key. 3 By pressing Cancel one or more times, you can back out of menus or messages. 4 For example, suppose you have retrieved a letter and are making some editing changes. 5 Press Retrieve (Shift-FlO) type musicbox.wkb for the filename, and then press Enter to retrieve a copy of the letter. 4 After making the necessary corrections, you are ready to save the document and clear the screen.

PAGE 131

Analysis. Again the given information in Sentence A refers to previous paragraphs. The sentence has. an inner logic because readers wouldn't need to seek help if they were not already using the program. Sentence B is subordinate because it discusses one of the tools (a noun similar in meaning and coherent with, "resources"). Repetition of the stem word "help" and the word "problem" add further coherence. Sentence C repeats the word "cancel" and gives more specific information about using the key. The introductory phrase "for example" in Sentence D expresses a logical, subordinate connection: it's an instance of the previous sentence. sentence E (numbered in the original text to show that it is a step in a procedure) explains how to carry out the situation in sentence D. The word "retrieve," repeated twice, connects the step with the example stated in D. Sentence F continues the example from D and uses a phrase synonymous with "editing changes." 123

PAGE 132

From Using WordPerfect, page 81: (A) 1 Deleting text is one of the most basic editing tools. (B) 2 With a typewriter, deleting text is (C) (D) (E) cumbersome. 3 Even simple errors require erasing, whiting out with correction fluid or tape, and backspacing endlessly to lift off or cover the error. 3 If substantial revision is necessary, the entire document must be retyped. 4 What a waste of time! (F) 2 With WordPerfect, deleting text is (G) easy. 3 You can delete single letters, entire words, whole sentences, complete paragraphs, or full pages with only a few keystrokes. Analysis. The sentences in these two paragraphs create a coordinate pattern. Sentence A defines a broad topic: the given information simply repeats the heading above the paragraphs. Sentence B also repeats the phrase "deleting text" but the logical connection isn't unless readers remember that the.authors frequently compare using WordPerfect to using a typewriter. Or until readers reach the parallel comparison in Sentence F. Sentences C and D both give instances of how cumbersome deleting text can be. The words "errors" and "revision" have a logical connection to "deleting text" because they supply a reason for doing it. In addition, 124

PAGE 133

the author reinforces the coordination by contrasting "siniple" with "substantive." Sentence E makes a comment on the process described by sentence D, but readers have to keep the entire main clause from D in short term memory to understand what "what" refers to. Sentence F repeats the phrase "deleting text," reinstating the focus of the paragraph. Since the sentence is introduced by a prepositional phrase that coordinates with sentence B, it helps readers organize levels of hierarchy in the macrostructure of their mental .text base. Sentence G repeats the stem word "delete" and defines what is meant by "easy" in the previous 125

PAGE 134

From 1-2-3 Tutorial, page 1: (A) 1 1-2-3 is a powerful tool. (B) 2 You can use 1-2-3 worksheets to organize your data in many useful ways. (C) .2 Before you can begin to take advantage of the power of 1-2-3, you must learn a few basic concepts and master a few basic skills. (D) 1 The fundamental structure for storing and organizing information in 1-2-3 is the worksheet. (E) 1 In this chapter you will learn how to start 1-2-3, how to identify the parts of a worksheet and move around in it, and how to use menus. (F) 2 Specific skills you will learn include erasing a cell, canceling an error, using 1-2-3's on-line Help facility, and changing the directory. (G) 1 Finally, you will learn how to leave the 1-2-3 worksheet and return to the computer's operating system. Analysis. Sentences in these two paragraph are predominantly coordinate, a pattern that emphasizes memory for detail, rather than memory for gist. In general, given information appears near the beginning of the sentence. Sentence D, however, begins with the new idea of "fundamental structure"; the adjective "fundamental" could be considered given information since it is synonymous with "basic" in the previous sentence but "structure" is synonymous with neither "concepts" nor "skills." Also, "structure," as 126

PAGE 135

the subject of sentence b, does not fit the pattern of topical focus used in the other sentences. In all but two of the seven sentences and in all the subordinate clauses, the subject is "you." The subject of the first sentence of this first chapter, 111-2-3," is also the subject of the book, which seems fitting. And the subject "specific skills" that sentence F will be subordinate to sentence E with its listing of general skills. But "structure" as the subject sentence D identifies one of the concepts the reader will be learning, concepts that are subordinate elements within sentences E, F, and G. Even though it has a synonymous tie to sentence c, "structure" doesn't "stick to the subject" of the second paragraph. Devices that strengthen the coherence of the paragraph include repetition of the key term 111-2-311 and temporal relationships indicated by "before" and "finally." 127

PAGE 136

From The ABC's of 1-2-3, page xxii: (A) 1 Because 1-2-3 is a powerful business tool, it can be complex. (B) 2 If you've never used a computer before, (C) (D) (E) just learning how to get started will take time. 3 The program manual and its accompanying on-screen lessons are excellent reference tools, but each requires several hours of reading before you can begin to take advantage of 1-2-3's capabilities. 4 The manual does not help the novice make use of the program from the very start, and the onscreen lessons do not leave room experimentation. 4 Each explains how to operate the program, but not how to apply it. Analysis: The given information in Sentence A is a summation of the previous pages in the text. The next two sentences reveal that the author has not made explicit coherent ties between all of the sentences. Sentence B contains no explicit information that was given in Sentence A. Readers have to make a bridging inference by making a connection between the text and their learning situation. If they do, the given information becomes "never used a computer before" and "learning how to get started. Logical coherence also exists between the complexity of 1-2-3 and the time 128

PAGE 137

needed for learning. Because these inferences are possible, Sentence B can be subordinate to sentence A. Sentence c also requires bridging inferences, since the idea of manuals and on-screen lessons must be derived from the readers' prior knowledge of the software package they presumably bought. Thus, since the manuals are subordinate to learning 1-2-3, C is subordinate to B. The next two sentences make assertions about the manuals and lessons stated. in C. Actually, Sentences D and E are not subordinate to all of c but only to the first clause in E. 129

PAGE 138

C. TEXTS USED FOR ANALYZING DENSITY The following sample texts were used for analyzing the density of new words presented within a 200-word excerpt. A I indicates the end of 200 words. All words considered new and specific to the learning task, including the name of the software program, are underlined. The bold text is reproduced as it appears in the original.

PAGE 139

From WordPerfect Workbook, page 66-68: In order to let you select exactly what you want to move, WordPerfect provides a Block feature that lets you do the highlighting yourself. Simply. turn on Block, use Home andjor the arrow keys to highlight the text, and then select Move. For example, try using Block to highlight the list. The cursor should already be at the beginning of the list. 17 Press Block (Alt-F4), .and then move the cursor down to the beginning of the paragraph below the list. Your screen should look similar to the one below, with the cursorunder the "I" in the word "In," and the list completely highlighted. A "Block on" message at the bottom of the screen lets you know that Block is on. 18 Press Move (Ctrl-F4), select Block (1), and then select (2) After selecting WordPerfect automatically turns off Block for you. With the list saved, you are ready to move back into the memo. 19 Press Switch (Shift-F3) to display the memo in the first document screen. 20 Press Enter to insert the list into the memo. Your screen should now look similar to the one below, with the cursor at the beginning of the list. Block is I a wonderful editing tool that can be used with many other WordPerfect features (e.g., deleting a block of text). Count: "new" words = 28 (14.0%) unique words = 13 ( 6.5%) 131

PAGE 140

From Using WordPerfect, page 131: Count: Highlighting a block of text is the first step in many WordPerfect operations. A highlighted block of text is singled out from the text around it. Whatever operation you next choose will perform its magic on only that block of text. Highlight the first paragraph of the memo you typed by completing these steps: 1. Press Home-Home-up-arrow to move the cursor to the beginning of the memo. 2. Press the up-arrow repeatedly until the cursor is positioned at the beginning of the first paragraph. 3. Press the Block key (Alt-F4 or F12) to turn on the Block command. Notice the Block on message flashing in the bottom left of your screen. 4. Move the cursor to the end of the first paragraph. The paragraph is.now highlighted, as shown in figure 4.11. Leave the block highlighted for the second part of the operation. The Block on message is still flashing on your screen, indicating that the highlighted block of text is ready for the second part of the operation. In this example, you want to change the first paragraph of text to bold face. To do this you simply press a single function key: Press the Bold key (F6) to boldface the highlighted I block of. text. "new" words 'llnique words = 19 (9.5%) = 12 (6.0%) 132

PAGE 141

From 1-2-3 Tutorial, page 31-32: Until now you have used 1-2-3 to record labels and numbers on the screen, just as you would on a piece of lined paper. With paper, however, you would have to do the arithmetic by hand or with a calculator. 1-2-3 can do it for you automatically. In this lesson, you will learn how to write formulas and copy those formulas to other locations in the worksheet. Retrieve the rNCOME2.WK1 file if it is not already on the screen Beginning with this lesson, whenever you see the word Enter in bold, it means type the material that follows and then press RETURN or an appropriate key. For example, Enter 9+5 means: Type 9+5 and press RETURN. Before you work with the numbers you entered in Lesson 2, try a few basic calculations in a different part of the worksheet. Press GOTO Type A21 and press RETURN In 1-2-3, formulas are expressions. When you write formulas, you can use the basics of addition,. subtraction, multiplication, division, and exponentiation as well as using advanced financial and statistical analysis. 1-2-3 will calculate the results automatically. First write the formula that adds two numbers. Be .careful not to put ariy spaces between I characters of a formula as you type them. Count: "new" words unique words = 23 (11.5%) = 12 ( "6. 0%) 133

PAGE 142

From The ABC's of 1-2-3, page 49-50: If you only used 1-2-3 to store information, it. wouldn't be much more than a very .expensive ledger pad. However, with formulas, some as simple as the ones you learned in Algebra 1, you can begin to calculate, analyze, compare, and project. Placed in individual cells, formulas tell 1-2-3 to perform calculations that can vary in complexity. A formula may be simple, such as one that adds numbers, or it may be complex, such as one that calculates your monthly mortgage payments. Take a look at the worksheet you've built so far. When you look down through the rows, you will notice three empty cells that are .crucial to this particular budget. They raise several questions: What is the profit on sales after the cost of goods is subtracted? What are the total expenses? What is the overall profit? Some simple formulas, entered in those cells, will provide the answers for you. Later, you can play "what if" by changing the numbers on the worksheet, and 1-2-3 will automatically adjust its findings to reflect you changes. When you enter a formula, interprets it as a value, which includes both formulas and numbers. A value is one of two I kinds of entries possible on the worksheet; the other is a label, which you are already familiar with. Count: "new" words unique words = 17 (8.5%) = 6 (3.0%) 134

PAGE 143

BIBLIOGRAPHY Anthony, carolyn. 1989. The volatile world of computer books. Publishers Weekly 24 November: 17-32. Bamberg, Betty. 1983. What makes a text coherent. College Composition and Communication 34(4):417-429. Barnett, George A., and carol Hughes. 1985. Communication theory and technical .communication. In Research in technical communication, ed. Michael G. Moran and Debra Journet, 39-83. Westport, CT:Greenwood Press. Beale, Walter H. 1987. A pragmatic theory of rhetoric. Carbondale, IL:Southern Illinois University Press. Beaugrande, Robert de. 1980. Text. discourse. and process: Toward a multidisciplinary science of texts Norwood, Nj:Ablex Publishing company. Beaugrande, Robert de, and Wolfgang 1981. Introduction to text linguistics. London:Longman Group Ltd. Bock, Michael. 1980. Some effects of titles on building and recalling text structures. Discourse Processes 3:301-311. Carroll, John M., Robert L. Mack, Clayton H. Lewis, Nancy L. Grischkowsky, and Scott Robertson. 1988. Exploring Exploring a Wordprocessor. In Effective documentation: What we have learned from the research, ed. stephen Doheny-Farina, 103-126. Cambridge, MA:The MIT. Press. Carroll, John M., Penny L. Smith-Kerker, Jim R. Ford, and Sandra A. Mazur-Rimetz. 1988. The minimal manual. In Effective documentation: What we have learned from the research, ed. Stephen Doheny-Farina, 73-102. Cambridge, MA:The MIT Press.

PAGE 144

Charney, Davida, Lynne Reder, and Gail Wells. 1988. Studies of elaboration in instructional texts. In Effective documentation: What we have learned from the research, ed. Stephen Doheny-Farina, 73-102. Cambridge, MA:The MIT Press. Christensen, Francis. 1967. Notes toward a new rhetoric. New York:Harper & Row. Crai)t, F.I.M., and R. s. Lockhart. 1972. Levels of processing: A framework for memory research. Journal of Verbal Learning and Verbal Behavior 11:671-684. Doheny-Farina, Stephen, ed. 1988. Effective documentation: What we have learned from the research. Cambridge, MA:The MIT Press. Duin, Ann Hill. 1989. Factors that influence how readers learn from text: Guidelines_for structuring technical documents. Technical Communication 36(2) :97-101. Ede, Lisa, and.Andrea Lunsford. 1984. Audience addressed/audience invoked: The role of audience in composition theory and pedagogy. College composition and Communication 35(2):155-171. Faigley, Lester, and Stephen P. Witte. 1983. Topical focus in technical writing. In New essays in technical and scientific communication: Research, theory. practice, ed. Paul v. Anderson, R. John Brockman, and Carolyn R. Miller, 59-68. Farmingdale, NY:Baywood Publishing Company. Felker, Daniel B., ed. 1980. Document design: A review of the relevant research. Washington, DC:American Institutes for Research. Felker, Daniel B., Frances Pickering, Veda R. Charrow, v. Melissa Holland, and Janice c. Redish. 1981. Guidelines for document designers. Washington. DC:American Institutes for Research. 136

PAGE 145

Fillmore, Charles J. 1968. The case for case. In Universals in linguistic theory, ed. Emmon Bach and Robert Harms. New York: Holt Rinehart and Winston, Inc. Floreak, Michael J. 1989. Designing forthe real world: Using research to turn a "target audience" into real people. Technical Communication 36(4):373-381. Flower, Linda, John R. Hayes, and Heidi Swarts. 1983. Revising functional documents: The scenario principle. In New essays in technical and scientific communication: Research. theory. practice, ed. Paul V. Anderson, R. John Brockman, Carolyn R. Miller, 41-58. Farmingdale, NY:Baywood Publishing Company. Gibson, Walker. 196. Tough. sweet. & stuffy: An essay on modern American prose styles. Bloomington, IN:Indiana University Press. Gillihan, Dana, and Jennifer Herrin. 1988. Evaluating product manuals for usability. Technical Communication 35(3):168-172. Goodin, George, and Kyle Perkins. 1982. Discourse analysis and the art of coherence. College English 44(1):57-63. Gould, Emilie, and Stephen Doheny-Farina. 1988. Studying usability in the field: Qualitative research techniques for technical communicators. In Effective documentation: What we have learned from the research, ed. Stephen Doheny-Farina, 329-343. Cambridge, MA:The MIT Press. Halloran, S.M., and A. Bradford. 1983. Figures of speech in the rhetoric of science and technology. In Essays on classical rhetoric and modern discourse, ed. Robert J. Conners, Lisa s. Ede, and Andrea Lunsford, 179-192. Carbondale, IL:Southern Illinois University Press. Hand, James D. 198.2. Brain functions during learning: Implications for text design. In The technology of text, Vol. 1, ed. Davi.d H. Jonassen, 91-120. Englewood Cliffs, NJ:Educational Technology Publications. 137

PAGE 146

Harris, Elizabeth. 1983. A theoretical perspective on "how to" discourse. In New essays in technical and scientific communication: Research. theory. practice, ed. Paul v. Anderson, R. John Brockman, and Carolyn R. Miller, 139-156. Farmingdale, NY: Baywood Publishing Company. Haviland, s., and H. 1974. What's new: Acquiring new information as a process of comprehension. Journal of Verbal Learning and Verbal Behavior 13:512-521. Houghton-Alice, Doann. 1985. Creating computer software user guides: From manuals to menus. New York:.McGrawHill. Huckin, Thomas N. 1983. A cognitive approach to readability. In New essays in technical and scientific communication: Research, theory .. practice, ed. Paul v. Anderson, R. John Brockman, and carolyn R. Miller, 90-108. Farmingdale, NY: Baywood Publishing Irwin, Judith Westphal. 1980. The effects of linguistic cohesion on prose comprehension. Journal of Reading Behavior 12(4):325-332. Jonassen, David, ed. 1982. Introduction to section one. In The technology of text, Vol.. 1, 5-12. Englewood Cliffs, NJ:Educational Technology Publications. Kallendorf, Craig, and Carol Kallndorf. 1985. The figures of speech, ethos, and Aristotle.: Notes toward a rhetoric of business communication. Journal of Business Communication 22(1):35-50. Kinneavy, James L. 1971. A theory of discourse. Englewood Cliffs, NJ: Prentice-Hall. Kintsch, Walter, and Teun A. van Dijk. 1978. Toward a model of text comprehension and production. Psychological Review 85(5):363-394. Kozminsky, Ely. 1977. Altering comprehension: the effects of biasing titles on text comprehension. Memory and Cognition 5(4):482-490. Lewis, Elaine. 1988. Design principles for pictorial information. In Effective documentation: What we have learned from the research, ed. Stephen DohenyFarina, 235-253. Cambridge, MA:The MIT Press. 138

PAGE 147

LeBlond, Geoffrey T., and Douglas Ford Cobb. 1985. Using 1-2-3. Indianapolis, IN:Que Corporation. Major, John H. 1989. What should you write: a user's guide, tutorial, reference manual, .or standard operating procedure? Technical Communication 36(2):130-135. Mandl, Heinz, and Steffen-Peter Ballstaedt. 1982. Effects of elaboration on recall of texts. In Discourse processing, eds. A. Flammer and W. Kintsch, 482-494. Amsterdam:North Holland Publishing Company. Mayer, Richard E. 1982. Instructional variables in text processing. In Discourse processing, ed. A. Flammer and w. Kintsch, 455-461. North Holland Publishing Company. Mirel, Barbara. 1988. Cognitive processing, text linguistics and documentation writing. Journal of Technical Writing and Communication 18(2):111-123. Norman, Donald A. 1976. Memory and attention. New York: John Wiley & Sons, Inc. Ogilvy, David. 1983. Ogilvv on advertising New York:Vintage Books. Ong, Walters. 1975. The writer's audience is always a fiction. PMLA 90:9-22. Pace, Ann Jaffe. 1982. Analyzing and describing the structure of text. In The technology of text, Vol. 1, ed. David H. Jonassen, Englewood Cliffs, NJ:Educational Technology Publications. Park, Douglas B. 1982. The meaning of 11audience.11 College _English 44(3):247-257. Penrose, John M. Jr., and Lawrence M. Seiford. 1988. Microcomputer users' preferences for software documentation: An analysis. Journal of Technical Writing and Communication 18(4):355-365. Price, Jonathan. 1984. How to write a computer manual: A handbook of software documentation. Menlo Park, CA:Benjamin cummings Publishing. 139

PAGE 148

Ramey, Judith. 1988. How people use computer documentation: Implications for book design. In Effective documentation: What we have learned from the research, ed. Stephen Doheny-Farina, 143-158. Cambridge, MA:The MIT Press. Ramsey, Richard David. 1980. Grammatical voice and person in technical writing: Results of a survey. Journal of Technical Writing and Communication 10(2):109113. Rihs-Middel, Margret. 1982. Expectancy structures in prose reading. In Discourse Processing ed. A. Flammer and w. Kintsch, 76-86. Amsterdam:North Holland Publishing Company. Rubens, Philip, and Brenda Knowles Rubens. 1988. Usability and format design. In Effective documentation: What we have learned from the research, ed. Stephen Doheny-Farina, 213-233. Cambridge, MA:The MIT Press. Rubin, Donald L. 1984. Social cognition and written communication. Written communication 1(2) :211-245. Rumelhart, D.E., and D. E. Norman. 1981. Analogical processes in learning. In Cognitive skills and their acquisition, ed. John A. Anderson, 335-359. Hillsdale, NJ:Lawrence Erlbaum Associates. Shriver, K., J. Hayes, c. Danley, w. Wulff, L. Davies, K. Cervoni, D. Graham, E. Floyd, and E. Bond. 1986. Designing computer documentation: A review of the relevant literature. Communication Design Center Technical Report No. 31. Pittsburgh, PA:Carnegie Mellon University. Sides, Charles H. 1989. What does Junghave to do with technical communication? Technical Communication 36(2):119-126. Simons, P. RobertJan. 1982. Concrete analogies as aids in learning from text. In Discourse processing, eds. A. Flammer and w. Kintsch, 462-471. North Holland Publishing Company. Solso, Robert L. 1988. Cognitive psychology. Boston:Allyn and Bacon, Inc. 140

PAGE 149

Tanner, Liz. 1989. Corporate Communications, WordPerfect Corporation, Orem, UT. Telephone interview, December 6. Wells, Brad. 1989. Buyer for computer books at the Tattered Cover, Denver, co. Telephone interview, December 6. 141

PAGE 150

TEXTS USED FOR ANALYSIS Gilbert, Chris, and Laurie Williams. 1989. The ABC's of 1-2-3, Release 2.2. San Francisco:Sybex. Lotus Development Corporation. Getting started, Tutorial, and Reference manual, Release 2. Cambridge, MA:Lotus Development Corporation. Stewart, Charles o. III. 1988. Using WordPerfect 5. Carmel, IN:Que Corporation. WordPerfect Corporation. 1988. WordPerfect and WordPerfect Workbook, Version 5.0. Orem, UT:WordPerfect Corporation. 142