MSU m‘.~fi RETURNING MATERIALS: Place in book drop to LIBRARJES remove this checkout from _agslzg:-al. your record. FINES will be charged if book is returned after the date stamped beIow. 11F!“ 31; m THE PURPOSES AND AUDIENCES OF SOFTWARE WRITING IN LARGE-SCALE TECHNICAL PROJECTS By Robert Bruce Fry, Jr. A DISSERTATION Submitted to Michigan State University in partial fulfillment of the requirements for the degree of DOCTOR OF PHILOSOPHY Department of English 1986 Copyright by ROBERT BRUCE FRY, JR. 1986 ABSTRACT THE PURPOSES AND AUDIENCES OF SOFTWARE WRITING IN LARGE-SCALE TECHNICAL PROJECTS By Robert Bruce Fry, Jr. This study examines the discourse traits of software writing in the context of large-scale projects, where many authors must address multiple audiences in a single text. This study first determines whether the traits of each text generally work together to achieve a single purpose despite the time constraints, organizational dilemmas, and problems of communication facing their authors during the writing process; it then investigates whether software writers in large projects sense their purposes and audiences, even though these authors must often address several audiences with diverse purposes. To answer these questions, this study first uses James Kinneavy's Theory 9f Discourse to discover the ways in which a proposal, several specifications and test documents, and a user document produced at a contemporary aerospace corporation, Lear Siegler, Inc./Instrument Division (LSI/ID), do or do not reflect writers' consistent purposes. The study then examines the Institute of Electrical and Electronic Engineers Transactions on Professional Communication, 1981-85, to find how contributors have discussed the purposes and audiences of engineer- ing writing and to develop the larger context of software writing at LSI/ID. The study next surveys 15 managers and coordinators at LSI/ID, to find how these individuals evaluate writers' senses of purpose and audience, and 15 writers and lead writers, to assess whether managers’ and coordinators' evaluations are accurate. The study concludes that the software texts from LSI/ID demon- strate consistent purposes and that the software writers surveyed have generally developed strong senses of purpose and audience. By using the Kinneavyan model, the study shows that the software texts have consistent purposes, that their logic, organization, and style work together to support unified purposes. By reviewing the surveys of software writers and their managers and coordinators, the study illus- trates software writers' well-developed senses of purpose and audience. Through these surveys, the study also shows that some writers have more finely developed senses of purpose and audience than others, and that these senses develop as functions of writers’ levels in the writing process, the types of writing they do, and their affiliations with projects. To the memory of Frances Ann Fry, 1924-1973. ii ACKNOWLEDGEMENTS I thank the Instrument Division of Lear Siegler for supporting this study with its financial resources, and many of its employees for their efforts on behalf of this project. In particular, I thank Rod Blom, Fred Boshoven, John Chapin, Bruce Chubb, Bob Gengle, and Gary VanDeVenter for their administrative guidance, and Dick Friedrich and Derek Hatley for their technical advice. In addition, I recognize the contribution of the 30 survey respondents, who took the time to answer my questions; the word processing specialists of Engineering Publica- tions, who taught me to use their equipment; and Skip Coryell, Jennifer Hickel, Sue Kadzban, Larry Strawn, and Char Sypien, who helped me to prepare the final manuscript. I also thank faculty members of Michigan State University for their direction. Dr. Jay Ludwig guided me from the outset of this study, and steered me to successful completion. Dr. Howard Anderson, Dr. Alan Hollingsworth, and Dr. Marilyn Wilson offered guidance and corrected my course. Finally, I recognize my family's contribution to this study. My parents, Mr. and Mrs. Robert Fry, Sr., and my wife's parents, Mr. and Mrs. Harold VanBroekhoven, Sr., helped make this project possible. My wife, Lois, gave me the moral support I needed to make it real. iii TABLE OF CONTENTS LIST OF TABLES LIST OF FIGURES INTRODUCTION CHAPTER 1 PART I: THE KINNEAVYAN MODEL REFERENCE DISCOURSE Reference Discourse: Logic Reference Discourse: Organization and Style Reference Discourse: A Summary PERSUASIVE DISCOURSE Persuasive Discourse: Logic Persuasive Discourse: Organization and Style SUMMARY: THE KINNEAVYAN MODEL PART II: THE KINNEAVYAN MODEL APPLIED TO SOFTWARE WRITING AT LEAR SIEGLER, INC./INSTRUMENT DIVISION THE PROPOSAL SPECIFICATIONS THE TEST DOCUMENT USER DOCUMENTATION SUMMARY CHAPTER 2 CONTRIBUTORS’ CONCEPT OF THE PURPOSES AND AUDIENCES OF ENGINEERING WRITING CONTRIBUTORS' CONCEPT OF THE WRITER'S AUDIENCE CONTRIBUTORS' CONCEPT OF THE WRITER'S TASK SUMMARY CHAPTER 3 INTERVIEWS WITH MANAGERS AND COORDINATORS OF WRITERS QUESTION 1: "Please describe the kinds of documentation which the customer or sponsor requires for each project." QUESTION 2: "What are the strengths of writers involved in the documentation process at LSI/ID? The weaknesses?” iv vi vii 77 81 87 98 108 110 110 115 120 QUESTION 3: "Who are the writers and end users of this documentation (in terms of positions and levels of expertise)?” QUESTION 4: "To what extent are the writers aware of the end users’ positions and levels of expertise?" QUESTION 5: "Do your writers have contact with end users before or while they write? And does this contact or lack of contact affect document quality?" QUESTION 6: "In the projects with which you work, is contact between writer and end user a practical possibility?” SUMMARY CHAPTER 4 INTERVIEWS WITH WRITERS AND LEAD WRITERS QUESTION 1: ”Please describe the forms of writing which you do for each project." QUESTION 2: "Please describe methods which you use to plan before you write. Please describe aids which you use to formulate ideas or expressions as you write. Please describe methods which you use to revise after you write." QUESTION 3: "Do you use storyboards? Please describe your use of storyboards. Have you participated in a walkthrough? Please describe it." QUESTION 4: ”When and why do you explain or discuss printed material aloud?" QUESTION 5: "When and why do you use a figure or table in printed material? What varieties of figures and tables do you use?" QUESTION 6: "If you are familiar with the structured approach, compare it with traditional methods of specification." QUESTION 7: "In general, how do you write in order to meet customer requirements?" SUMMARY CONCLUSION APPENDIX LIST OF WORKS CITED 124 129 133 137 141 145 145 148 153 162 168 173 178 183 189 191 195 210 LIST OF TABLES Table 1. Managers’ and Coordinators’ Positions and Affiliations with Projects Table 2. Question 1: "Please describe the kinds of documenta- tion which the customer or sponsor requires for each project." Table 3. Question 2: "What are the strengths of writers in- volved in the documentation process at LSI/ID? The weak- nesses?” Table 4. Question 3: "Who are the writers and end users of this documentation (in terms of positions and levels of expertise)?" Table 5. Question 4: "To what extent are the writers aware of the end users’ positions and levels of expertise?" Table 6. Question 5: "Do your writers have contact with end users before or while they write? And does this contact or lack of contact affect document quality?" Table 7. Question 6: "In the projects with which you work, is contact between writer and end user a practical possi- bility?" Table 8. A Summary of the Survey Results Table 9. Writers’ and Lead Writers’ Positions and Affiliations with Projects Table 10. Question 1: "Please describe the forms of writing which you do for each project." Table 11. Question 2: "Please describe methods which you use to plan before you write. Please describe aids which you use to formulate ideas or expressions as you write. Please describe methods which you use to revise after you write." Table 12. Question 3: "Do you use storyboards? Please describe your use of storyboards. Have you participated in a walkthrough? Please describe it." Table 13. Question 4: "When and why do you explain or discuss printed material aloud?" Table 14. Question 5: "When and why do you use a figure or table in printed material? What varieties of figures and tables do you use?" Table 15. Question 6: "If you are familiar with the structured approach, compare it with traditional methods of speci- fication." Table 16. Question 7: "In general, how do you write in order to meet customer requirements?" Table 17. Respondents’ Suggestions for Content of Class vi 111 117 122 126 131 135 139 142 146 150 156 165 170 175 180 185 199 Figure Figure Figure Figure Figure Figure Figure Figure Figure Figure LIST OF FIGURES Context Diagram Data Flow Diagram Second-Level Data Flow Diagram Page from 3 Requirements Dictionary Structure Chart Pseudocode Test Cases Control/Display Unit Selection Table Test Menu vii INTRODUCTION Since 1975, several commentators from the field of electrical engineering with diverse experience in practical software applications have described the effects of time constraints, organizational di- lemmas, and difficulties of communication on large-scale software projects. In that year, Frederick Brooks, a professor of computer science with a background in large-scale software projects at Inter- national Business Machines, explained how the first of these factors may defeat software system developers. The less the time allotted to a software project, the larger the number of participants assigned to this project. The larger the number of participants, the more time they must spend communicating with one another to coordinate their efforts. The more time these participants spend communicating, the longer the time necessary to complete the project. Project developers thus find themselves in a self-defeating cycle: the very measures they take to meet time constraints ultimately produce delay. Brooks declared, "...our estimating techniques fallaciously confuse effort with progress, hiding the assumption that men and months are inter- changeable" (14). Project developers assume that each man assigned to a project per month produces an additional man-month of work (thus the title of Brooks’ book: The Mythical Man-Month). Instead, developers find, each added person’s need to communicate with existing staff ultimately slows the course of a project. "Men and months are inter- changeable commodities only when a task can be partitioned among many workers with no communication among them" (16). Workers added to a large software project create a larger internal audience--an "added burden of communication" that veteran workers must carry in addition to their existing duties (18). Slower rather than more rapid progress results. In 1978, Tom DeMarco, a consultant on systems analysis for busi- ness applications, described the corporate organizational dilemmas that often defeat software developers. In Structured Analysis and System Specification, DeMarco explained that software projects in a producing organization require developers to serve three classes of users within the procuring organization--the system’s operators, middle managers, and upper managers. Furthermore, if the developers must serve users in more than one organization, the number of users becomes "as much as three times the number of organizations" (14). For instance, if developers must serve users in both the producing and procuring organizations, they can expect six classes of users: Operators, middle managers, and upper managers in each of the two organizations. The developers must often divide the production of software into several team efforts, assign each team in the producing organization to address the needs of a specific subgroup in the procuring organization (opera- tors, middle managers, or upper managers), and insure that each software team works with others so as to achieve a coherent effort. In 1983, the Institute of Electrical and Electronic Engineers Computer Society published a Tutorial 92 Software Design Techniques, a volume including several articles from the late 19705 and early 19803 that explained how the time constraints and organizational complexities of large software projects result in problems of communication. Anthony Wasserman, Professor of Medical Information Science and author of seven books on software development, explained how the time con- straints on large software projects work against effective communi- cation by preventing "communication between the user community and the development organization" and inhibiting "intermediate steps during the project at which project management and the customer [can] review pro- gress and determine the system status." The system developers have insufficient time to communicate with the customer during the course of a project; or, at least, they believe as much. According to Wasserman, developers’ inability or unwillingness to devote this time often defeated their efforts in the 1960s and early 19705: "the developers didn’t orient the system to the end users, who then rejected the system as being difficult to learn or difficult to use" (43). In another article from the same volume, Douglas Ross and Kenneth Schoman, staff members of an engineering consulting firm, further explained how the organizational complexities of large-scalesoftware projects have produced problems of communication, particularly, written communi- cation. Ross and Schoman explained that the form of a software document, including "paging, paragraphing, use of graphics, document organization, and so forth" must fit a complex organizational con- text--including the customer and the system developers and their varied purposes (89). The form of the text must promote a general, non- technical description of a system for the customer; on the other hand, the same form must promote a precise, technical description for the developers. The form that suits the customer may seem ambiguous to the developers, and the form that suits the developers may seem obscure to the customer. The software writer often fails to find a form that satisfies both audiences. By describing the time constraints, organizational dilemmas, and problems of communication that confront software developers, Brooks, DeMarco, Wasserman, and Ross and Schoman set the context for the two questions this study will pose and answer: First, despite the diffi- culties facing software developers, do the texts they produce demon- strate unified purposes--do the traits of each text generally work together to achieve a single aim? That is, does an analysis of each text reveal that one aspect of software development, software writing, can achieve a unified purpose despite its potentially confusing context? Second, despite time constraints, organizational diffi- culties, and problems of communication, do individual writers maintain firm senses of their purposes and audiences--can they explain the purposes for the methods they use and identify their audiences? Brooks, DeMarco, Wasserman, and Ross and Schoman have described the difficult context in which software writers at IBM and other corporations have worked in the 1960s through early 19805. This study will investigate whether software writers in one particular corporation, Lear Siegler, Inc./Instrument Division (LSI/ID), can overcome such difficulties in the mid-19805, whether the texts they compose demonstrate coherent purposes, and whether, despite continuing time constraints and organizational dilemmas, writers can explain the methods they use to write and identify the audiences they address. To accomplish this task, this dissertation will look at software writing in four ways through its chapter divisions. First, chapter 1 will look at the texts of software writing themselves, to judge, largely on the basis of evidence internal to the texts, whether they reveal unified purposes in a general way. By examining the logic, organization, and style of each text, the chapter will determine whether these components work together to attain a unified purpose. Chapter 1 will first summarize James Kinneavy’s Theory pf Discourse, its classification of all discourse by four aims, and, particularly, its description of persuasive and reference discourse. The chapter will then show that examples of software texts written at LSI/ID--a proposal, several specifications and test documents, and a user document--demonstrate the aim of either persuasion or reference discourse in a unified way: the logic, organization, and style of these texts work together coherently to achieve a single aim. Specifically, the proposal achieves a persuasive aim; specifications and test documents attain the aim of scientific reference discourse; and the user document demonstrates the aim of informative reference discourse. Chapter 1 will show that software texts, in a general way, demonstrate coherent and definable aims. Chapter 2 will establish the context in which these texts exist-- the large engineering corporation--by showing how contributors to the Institute pf Electrical and Electronic Engineers Transactions 92 Pro- fessional Communication, 1981-85, have examined writers’ concepts of purpose and audience, identified their audiences, and described their tasks in a corporate setting. The chapter will determine the degree to which contributors to the IEEE Transactions show awareness of problems involved in software writing in a large corporate context and solutions. to these problems. With a sample of 146 articles and 31 book reviews from the major periodical on communication in the electrical engi- neering field, chapter 2 will show how IEEE contributors have evaluated engineering writers’ senses of purpose and audience, described their audiences, and analyzed their tasks within the corporate sphere. The chapter will describe IEEE contributors’ concepts of purpose and audi- ence in corporate engineering settings. Some contributors have failed to develop these concepts, but others have offered much to illuminate them. First, many IEEE contributors have shown that writers should develop stronger senses of purpose and audience. Second, many have recognized that engineering writers address a diverse audience. Third, IEEE contributors have developed a fairly complete view of the writer’s task: to define complex purposes and audiences as well as develop stylistic and organizational strategies for planning, writing, and revision. Nevertheless, IEEE contributors have not described the complex kinds of writing and audience that confront writers in large- scale software projects. The profession, chapter 2 will suggest, can better identify the bearing of concepts like purpose and audience on large-scale projects, which include numerous authors and audiences. In its third and fourth chapters, this study will focus directly on communication in large-scale software projects at Lear Siegler, Inc./Instrument Division (LSI/ID), to discover whether writers in this specific setting are aware of their purposes and audiences. Through analysis of interviews with 15 managers and coordinators of writers from LSI/ID, chapter 3 will show how managers and coordinators evaluate writers’ awareness of purpose and audience. The chapter will thus examine the purposes and audiences of software writers from the vantage point of these respondents, who should be able to describe how these writers function in a specific corporate context. The chapter will show that these managers and coordinators do not generally believe that writers’ awareness of purpose and audience rates high concern. Some managers and coordinators believe writers need a stronger sense of purpose, but many rate writers’ awareness of audience as unimportant. Chapter 3 will also describe managers' and coordinators’ hypothe- ses about the variables that influence writers' senses of purpose and audience. Managers and coordinators generally suggest that writers’ awareness of purpose and audience is a function of their levels of involvement in software writing, the kinds of writing they produce, and their affiliations with projects. According to managers and coordi- nators, lead writers know more of purpose and audience than the writers under them; writers of user documents know more than writers of specifications; and writers affiliated with a commercial customer know more than those who serve a military audience. By summarizing interviews with 15 writers and lead writers, chapter 4 will show what awareness of purpose and audience writers themselves demonstrate. To evaluate their senses of purpose and audience, chapter 4 will survey writers and lead writers, discover whether these individuals demonstrate strong or weak senses of purpose and audience, and test whether different categories of writers have developed these senses to the relative degrees managers and coordi- nators specify. The chapter will show that these individuals have relatively sophisticated senses of purpose and audience, and that these writers value awareness of audience more than their managers and coordinators do. While the chapter will thus challenge managers' and coordinators’ evaluation of how useful the senses of purpose and audience prove to be in a corporate context, it will confirm several hypotheses the managers and coordinators set forward. Lead writers or lead project engineers have developed stronger senses of purpose and audience than the writers who work under them; writers of user docu- ments do know more of their purposes and audiences than writers of specifications; and writers who address a commercial customer do demonstrate stronger senses of purpose and audience than those writing for a military audience. This study will conclude that writers in large-scale software pro- jects have developed generally strong senses of purpose and audience, at least, in the context of one corporation. Software writers can compose written communication with a clear sense of purpose. Despite the time constraints and organizational dilemmas confronting them and the related difficulties of communication, writers produce texts that demonstrate unified purposes. Software writers at Lear Siegler, Inc./Instrument Division (LSI/ID) produce texts with logical, organiza- tional, and stylistic traits that, looked at from a general perspec- tive, achieve a unified purpose. On a very general level, these writers can describe the purposes and audiences of their writing with considerable sophistication. Lead writers and writers at LSI/ID are able to clarify how the factors of purpose and audience operate within written communication about software, and they explain much about how the senses of purpose and audience develop in large corporate contexts. Though managers and coordinators of writers at LSI/ID question writers’ awareness of purpose and audience, the writers themselves can usually articulate rationales for the methods they use to write and can describe their audiences in some detail. This study will thus illustrate the strengths of software writers at LSI/ID and similar companies. Yet the study will also show that different classes of participants in the software writing process 10 are aware of purpose and audience to differing extents. Software writers’ senses of purpose and audience are generally strong, but some writers know more about purpose and audience than others. The comments of the respondents from the two surveys suggest that awareness of purpose and audience is a function of three variables: writers’ level of involvement in the process of software writing, the kinds of writing they do, and their affiliations with projects. Particularly, lead writers know more about purpose and audience than those who work under them, writers of user documents know more about these factors than writers of specifications, and writers who address a commercial (non- military) customer know more about these factors than those who write for a military audience. As the Appendix will show, to increase awareness of purpose and audience among those with a lower level of awareness, Lear Siegler, Inc./Instrument Division and similar companies can promote a sharing of knowledge between those with differing levels of awareness--between lead writers and writers, writers of user documents and writers of specifications, and writers in the commercial and military spheres. By this means, those who know more about purpose and audience in the specific context of large-scale software projects can share their knowledge with those who know less. CHAPTER 1 The introduction has reviewed several commentators’ accounts of software developers’ dilemma in the 19605 through the early 1980s--the .time constraints, organizational problems, and communication diffi- culties these commentators described. To discover whether the effects of this dilemma are evident in the texts of software writing produced at one large corporation, Lear Siegler, Inc./Instrument Division (LSI/ID), chapter 1 will examine these texts to find whether they embody unified purposes. The chapter will examine each major category of software writing--proposal, specification, test document, and user document--to discover a unified purpose in its logic, organization, and style. Chapter 1 will apply James Kinneavy’s model of discourse to these texts of software writing and show that a unified purpose of communi- cation becomes apparent in each. The chapter will analyze the logic, organization, and style of each text to show how these elements support and exemplify a single purpose. In order to analyze each text, the chapter will apply Kinneavy’s Theory 9f Discourse. In its first part, the chapter will summarize the four aims of discourse Kinneavy dis- cusses: reference, persuasion, literature, and expression. For each category, chapter 1 will show how the logic, organization, and style of the text work together to achieve the aim. The chapter will then discuss Kinneavy’s development of the two categories most relevant to 11 12 this study--reference and persuasion--to establish the background for its major task: to use these two categories to show that the purposes of software writing at LSI/ID are clear. In its second part, the chapter will show how proposals, specifications, test documents, and user documents embody the Kinneavyan aims of reference and persuasion and their associated logical, organizational, and stylistic traits. By examining texts in these categories of reference and persuasion, the chapter will demonstrate these texts’ unified aims. PART I: THE KINNEAVYAN MODEL James Kinneavy provides an appropriate instrument for the chap- ter’s task. In A Theory 3f Discourse, Kinneavy classifies all dis- course by its aim, its overall purpose revealed in the text. Kinneavy contends that the writer and reader may influence aim, but that they are not its determinants. Rather than the encoder or decoder being the determinants of aim, it seems better to find the aim which is embodied in the text itself--given the qualifications of situation and cul- ture...(Kinneavy 49) Kinneavy recognizes but circumscribes the role of the encoder and decoder in discourse, in the case of this study, the writer and reader of software documentation. His model uses the text, not the relation- ship between writer and audience, as a guide to the aims of discourse. Kinneavy acknowledges that aim "is partly determined by the cultural context and the situational context in both of which the text of the 13 discourse is a part" (49), but, throughout A Theory of Discourse, he abstracts the aims of discourse from the qualities of text rather than from knowledge of writer or reader. He allows for expressive and persuasive discourse, focusing on the writer and audience, respec- tively, but he draws their characteristics from the text itself. He admits that traditional classification has emphasized the encoder’s aims for discourse. ”Thus rhetoric meant language intended to per- suade; logic meant language used to demonstrate; and dialectic...meant language used to explore for truth" (50). But Kinneavy limits refer- ence to the writer’s purpose in determining aim. Kinneavy acknowledges the reader’s role in determining the purpose of discourse: "science, literature, even expressive utterances are all destined for receptors of some sort," but he suggests that examining the text itself, not studying what the reader does with it, is the best guide to establish- ing its aim (59). Kinneavy identifies each of the four primary aims of discourse by its respective focus: reference discourse focuses on reality; per- suasive discourse focuses on the decoder; literary discourse focuses on the signal; and expressive discourse focuses on the encoder. Reference discourse derives its inherent nature entirely from its focus on reality. Kinneavy divides reference discourse into three categories that refer to reality with differing levels of probability. Informa- tive discourse establishes its level of probability by incorporating factual (that is, verifiable) data, but it does not attempt to prove 14 its propositions. For instance, a news story makes assertions that another source can corroborate, but it does not prove these assertions logically. Scientific discourse estabishes its level of probability by developing conclusions from premises through rigorous logic. Explora- tory discourse discovers conclusions on the basis of premises, but it does not prove these conclusions logically. Thus, a panel discussion arrives at consensus without step-by-step proof of its logic. Refer- ence discourse thus includes three subdivisions, informative, scien- tific, and exploratory discourse, that refer to reality with differing levels of probability: informative discourse states facts, that is, verifiable assertions, about reality; scientific discourse proves propositions about reality; and exploratory discourse discovers provable propositions about reality. In their respective foci on reality, all forms of reference dis- course distinguish themselves from persuasive discourse, "which is primarily focused on the decoder and attempts to elicit from him a specific action or emotion or conviction" (211). Kinneavy admits that all discourse posits a receptor, but asserts "that the receptor of the language process is contracted immediately in persuasion and mediately in the other three uses of the language" (59-60). Persuasion explic- itly solicits acceptance from its audience, whereas reference, expres- sion, and literary discourse merely assume that an audience will respond appropriately if they meet their primary aims--representation of reality, expression of self, and development of an adequate literary structure. 15 Persuasion includes "political propaganda, religious preaching, and advertising," which are "clear examples" of its propensity to change the perspective of an audience in a desired direction (218). Kinneavy admits that "some examples of persuasion are considerably more subtle than these"--though he does not specifically cite such texts (218-19). Persuasion need not purposefully distort reality--it differs from reference discourse only in the lower level of probability which its "truths" about reality represent. Persuasion values "truths" primarily for its audience’s willingness to accept them as real rather than their implicit reference to reality (219). One theory of art would have literary discourse as well as per- suasion focus on the audience (327-33). Kinneavy discounts this pragmatic theory by arguing that it does not distinguish literature "from... propaganda" (333). He likewise challenges the mimetic and expressive theories of art, which describe literature in terms common to reference and expressive discourse (313-26). Only the objective theory of literature accounts for the qualities of this literary object by holding the "art object or product" itself central (334). This theory stresses "the characteristics of the object that establish it as artistic"--its "formal or structural" qualities (334). These qualities of a poem or any other work of art operate ”just as logically" as proof, discovery, or factuality in scientific, exploratory, or informa- tive discourse. Yet these qualities work primarily in relationship to one another within the work; only secondarily, in relationship to the external reality, the audience, or the author. 16 In contrast, the qualities of expressive discourse develop from the relationship between the author and the text. This discourse assumes the author’s subjective viewpoint as its aim: it represents the world, addresses the audience, and uses the signal to further the author’s need for self-expression. Expressive discourse makes all its other three components subject to the author’s perspective. It brings Sartre’s "Being-in-the-World," "Being-for-others," and "Style”-- phenomenological categories corresponding to the reality, decoder, and signal, the foci of reference, persuasive, and literary discourse of Kinneavy’s model-~under control of "Being-for-Itself," corresponding to the encoder (405). In a sense, the logic of any given expressive text is unique to its author. Each author of such discourse realizes a distinctive combination of ”some emotional and some intellectual components," a "unification [which] can be called intuition" (421). This logic’s intellectual components may include elements common to reference, persuasion, or literature, but the encoder’s emotional state bends these more "objective" logics to a subjective view. Kinneavy, then, provides an appropriate instrument to define the purposes of software writing by isolating aim or purpose from other variables. He explains that neither the author nor the audience nor the situational or cultural context can determine the purpose of a text: the purpose is implicit in the text itself. He further explains that we may assign the purposes implied in texts to four relatively distinct categories: reference, persuasion, literature, and expression. 17 Reference discourse distinguishes itself by its focus on reality; persuasive discourse shows its nature by attempting to influence its audience; literary discourse derives its qualities by emphasizing the integrity of its parts; and expressive discourse seeks first to represent its author’s intellectual or emotional state. Though these categories of discourse have their distinct foci on reality, audience, sign, and author, all show these distinctive traits in the text itself. This chapter will now examine reference and persuasion--the two forms of discourse prevalent in software writing at LSI/ID--in more detail. The chapter will explain the overall character and distinctive logic of each form of reference discourse--informative, scientific, and exploratory--and show how organizational and stylistic traits reinforce this character and logic. The chapter will then describe the overall character and distinctive logic, organization, and style of persuasive discourse. REFERENCE DISCOURSE Kinneavy states the definitions of informative, scientific, and exploratory reference discourse by describing what the text itself does rather than what the encoder or decoder does with it: scientific reference discourse proves a point "by arguing from accepted premises" (deduction) or "generalizing from particulars" (induction); informative reference discourse reports or summarizes; and exploratory reference l8 discourse proposes "a solution to problems" (61). The texts of reference discourse in these categories have their respective logical, organizational, and stylistic traits, but all share a common purpose which distinguishes them from other discourse: reference to reality. The traits of reference discourse all reflect this focus on reality. In general, each category refers to reality with a given level of probability that establishes the pattern for its logic, organization, and style. Informative, scientific, and exploratory discourse each refer to reality with a differing level of probability: If the reality is conceived as known and the facts about it are simply relayed to the decoder, there is an informative use of language. If this information is systematized and accompanied by demonstrative proof of its validity, there is a scientific use of language. If the reality is not known but being sought, there is an exploratory use of language. (39) Informative discourse describes reality without proof: it assumes the factuality of its object. Informative discourse achieves relevance to reality, but it rests on probability rather than proof. Its logic rests on propositions "capable of being subjected to empirical veri- fication": statements which scientific discourse may prove (92). Informative discourse also attempts to achieve "relevance to the users" (90). It organizes its content to cover all questions implied in its topic--all questions its audience would probably ask concerning this topic. Its stylistic traits control the level of probability in a statement--what may be unpredictable to different audiences--in order to make the statement not only informative but also understandable. 19 Scientific discourse proves pr0positions about reality; thus it demonstrates truth. The texts of scientific discourse take a proof- orientation: their logic verifies possible truths such as those proposed by exploratory discourse. They may incorporate various modes as organizational strategies ("there can be scientific description, classifications, narratives, and evaluations"), but all with the same end: proof (86). These texts abstract their limited subject matter, the "formal object," from the "material object," the reality we perceive with our senses. They investigate physical phenomena by using "investigative and demonstrative procedures" and from these phenomena derive postulates several steps removed from the plane at which human agents operate (80). This level of abstraction places scientific texts at a distance from their audience: Science achieves its communication successfully by assuming a specific kind of audience and then focusing attention on that which is being talked about--some aspect of reality. Indeed, mechanical rules of scientific writing by some textbooks and some scientific periodicals even forbid the advertence to the addressee within the scientific article. The argument speaks for itself--"res ipsa loquitor," says the old legal cliché. (59) The style of scientific texts achieves the abstract description of physical reality by becoming "’thing’-oriented, not person-oriented" (88). The texts of scientific discourse adopt an impersonal style, excluding specific reference to the writer or reader. Exploratory discourse establishes a given proposition about reality as feasible; therefore, it demonstrates possibility. The texts of exploratory reference discourse share with those of scientific and 20 informative discourse a relevance to reality. These texts pose the questions about reality which informative discourse answers and scientific discourse proves (89). Exploratory discourse differs from scientific and informative discourse primarily in the degree of proba- bility its conclusions imply: the propositions of exploratory discourse ’ as the term "essay" suggests (97). Scientific are "not conclusive,’ discourse proves assertions with limited conclusiveness, as its deductive-inductive structure reveals; and informative discourse states factual, that is, highly probable, propositions. Exploratory texts distinguish themselves from other forms of reference discourse through the logic of discovery, as opposed to proof or probability. Explora- tion requires the author or reader to join a body of humanity by assenting to "accepted notions" (102). This "projection of the known to explain the unknown" (103) begins with axioms established by proof or probability. But exploratory discourse does not rest with such accepted notions; instead, it challenges these premises to show that "the dogma no longer provides a framework for the solution, [that] a new framework must be sought elsewhere" (103). Its organization and style follow this logic of exploration by adopting formats and media conducive to the continual reformulation and qualification of asser- tions, such as dialogue or panel discussion. 21 Reference Discourse: Logic The organization and style of reference discourse develop around its logic. The organization and style of informative discourse generally follow the patterns suggested by the informative logics of factuality, comprehensiveness, and surprise value. The organization and style of scientific discourse support its deductive-inductive logic. And the organization and style of exploratory discourse favor the logic of discovery. "The purpose of scientific logic is to demonstrate the truth or validity of a referential assertion with as much certainty as the techniques of the given logic can achieve” (108). And the given logic of scientific discourse is deductive-inductive proof. Its deductive logic demonstrates how applications stem from generalizations by "rules of inference" (117), and its inductive logic proves these generaliza- tions by determining "the degree of probability which the evidence actually offers for the generalization" (110). Kinneavy maintains no neat separation of deductive from inductive inference"; indeed, he describes them as complementary components of a single text (118). Kinneavy notes Newton's remark that we stand "on the shoulders of giants" (77), that our scientific assumptions, including deductive- inductive logic, rely on a long history of western thought, and that other cultures, ancient and modern, may challenge these assumptions (78). Nevertheless, western culture accepts this logic as a strong, perfect proof. 22 The texts of informative discourse rely on three logics: factu- ality, comprehensiveness, and surprise value. First, they base their assertions on fact: "sense data or observable data or measurable data" (130). While informative texts do not attain the level of proof at which scientific discourse arrives through its deductive-inductive logic, they do establish a large degree of probability through reliance on verifiable data. Second, the texts of informative discourse attempt comprehensiveness by answering the questions implicit in a topic: providing all the facts which the decoder will probably require. And third, they develop surprise value by asserting the unpredictable: depending on the improbability that the audience already knows these facts (134). Factuality and comprehensiveness somewhat depend on the decoder--what the audience will accept as fact and what information they need for complete understanding. Surprise value, however, depends primarily on supposition about audience: the assumption that certain facts will invoke surprise in the decoder. These facts usually take a place at the beginning of the discourse, either to encourage pleasant surprise or to provide a context for the remainder of the discourse. The logic of exploratory discourse rests on discovery rather than proof or probability. The encoder of exploratory discourse tries to account for "inconsistencies between the inferences which should follow logically from the axioms and theorems of the [current] dogma and the observed facts or inferences known from other sources" (142); to seek a new model which accounts for these observable effects; and to make "the 23 phenomena intelligible" by deriving a new premise (Kinneavy, quoting Smith 143). To define the encoder’s logic, Kinneavy cites Peirce, Day, and Harrah, who "all distinguish what they call ’abduction’ or ’retro- duction’ from induction and deduction" (142). Abduction passes from conclusion to premise (from "some state of affairs to be explained” to a hypothesis) rather than vice versa, like reverse deduction (Kinneavy, quoting Smith 143). The encoder of exploratory discourse uses this logic of discovery by considering an effect and postulating the con- ditions necessary to bring it about. Reference Discourse: Organization and Style Scientific discourse generally follows the pattern of organization suggested by its deductive-inductive logic and adOpts the style appro- priate to its proof-orientation and select audience. Often, "deductive logic provides the macrostructure and inductive the microstructure," so that scientific articles begin with general principles from which they later derive particulars or use the "inverted induction," which presents "the particulars first" and follows up ”with a generalization" (153). Whichever pattern it follows, the organization of scientific discourse follows the general aim of reference discourse--relevance to reality--and its specific deductive-inductive logic. The style of scientific discourse reflects the same aim by excluding mention of both encoder and decoder "to allow the control to come from the subject 24 matter" and by relying on the deductive-inductive framework for a com- prehensible context in which to place this subject matter (174). Scientific discourse assumes a restricted audience within the context of a given technical periodical; it adopts a tool appropriate to this audience--the formal medium of "sustained written prose" (l71)--and excludes "modern popular media... as vehicles of scientific thought" (172). It often uses the passive voice; employs nouns as adjectives, adverbs, and verbs; and has peculiar "graphemic features," including "abbreviations, dialectal symbols, special fonts, even a pure numeric outline form rather than the combined Roman and alphabetic system” (179). These stylistic characteristics may confuse the novice but suit the presumed audience of experts. They support the same aim as the deductive-inductive logic and organization of scientific discourse: rigorous proof of probable truths. Similarly, the organization and style of informative texts join their logic to support the primary aim of all reference discourse and a secondary emphasis--informativeness, including considerations of audi- ence. The organization generally adopts the patterns suggested by the three types of informative logic: factuality, surprise value, and comprehensiveness. The organization may follow the logic of factuality by relating empirical data in the appropriate mode: narrative for chronological or causal logic; description for part-to-part or part- to-whole logic; classification for categorizing logic; and evaluation for discriminating logic. Informative discourse may facilitate the 25 logic of comprehensiveness by adopting the who-what-where-when-why news-story pattern or the A-to-Z "encyclopedic" organization (161). The organization may also follow the logic of surprise value: stating "the most important facts first" in the manner of a news story (160). This placement of the important facts--especially if they are new to the audience--may inspire pleasant surprise. Thus Kinneavy comments that "factual" and "comprehensive" informative discourse may avoid becoming "hackneyed" through surprise value (135). In "some kinds of informative discourse, such as journalism, the surprise statements are often clustered in the beginning of the discourse" (134). Kinneavy cites the surprise opening, most common in journalism and everyday conversation, as an example of this organization. A news story often presents those facts its audience will find most remarkable in its opening line. But the term "surprise value" implies a second rationale for the placement of important facts first: the audience may need to know these facts before it can understand the remainder of the dis- course. Informative discourse places some facts first because they are both conducive to surprise and fundamental to understanding. Kinneavy " where "the surprise value of state- describes "the scientific essay, ments may continue unabated throughout" (134). In other words, the scientific essay (or informative essay on a technical subject) imparts new information throughout its entire introduction, body, and con- clusion, not just at the outset. 26 The style of informative discourse supports the logic of factu- ality by adopting a voice ("nonintrusion of [the] encoder") that favors empirical data; and it promotes comprehensiveness through its reliance on media conducive to reportorial accuracy: journalism, letters and reports, textbooks, nonfiction bestsellers, and "oral-aural output" (180). This style facilitates surprise value--perhaps a "sense of sensationalism" common in news headlines (183)--and it usually con- siders the decoder by attending to readability, sometimes in conformity to yardsticks like the Flesch and Gunning formulas (181-82). The organization and style of informative reference discourse reflect both primary and secondary aims: relevance to reality, through factuality and comprehensiveness; relevance to audience, through surprise value and readability. The organization and style of exploratory discourse also directly reflect its aim and logic. Its "organizational concerns...are a matter of the art and medium in which the discourse is presented." Explora- tory discourse allows several voices to present hypotheses for testing. Its written form is usually "dialogue"; its oral form, "panel dis- cussion," in contrast to the sustained monologue of scientific dis- course (162). These media allow exploratory discourse to advance from a state of "dogma" to a new understanding through the process of abduction, from conclusions (observable conditions) to premises through a process that tests multiple hypotheses (142). Stylistic traits support an exploratory aim by preferring "dialectical" opposition to 27 "rigid objective control" and the "tentativeness" of the purposefully metaphorical to the solidity of the literal (187, 188). Organization and style join with logic to support the aim of exploratory texts. Reference Discourse: A Summary Kinneavy analyzes the aims of scientific, informative, and exploratory texts and finds a consistent focus on reality. He de- scribes their respective approaches to this focus--the proof of solutions to questions regarding this reality; the reporting of probable solutions to such questions; and the discovery of questions and solutions. In all cases, he finds that the logic, style, and organization of these texts support both the overall aim of reference discourse--relevance to reality--and their respective approaches to this focus. PERSUASIVE DISCOURSE Kinneavy differentiates persuasive from reference discourse primarily by its emphasis on the audience. The audiences of scien- tific, informative, and exploratory discourse are secondary concerns-- all these forms of discourse make reality their primary focus; in contrast, persuasive discourse makes the audience its center of atten- tion. Persuasive discourse would win the hearer "to some new 28 intellectual conviction, or to a new emotional attitude..." (219). Like reference discourse, persuasive discourse embodies a logic that promotes its aim. All persuasive discourse focuses on the decoder; however, within the logic of persuasion are three divisions--the ethical, pathetic, and logical arguments--that emphasize the encoder, decoder, and reality, respectively (236-63). The aim of persuasion is to change the decoder’s perspective, but the logic of persuasion may at times focus on the encoder or reality to accomplish the aim of the discourse. The organization and style of persuasive discourse likewise support its aim. The classical organization of persuasion involves a tripartite appeal to its hearers: a beginning, the entrance and narration; a middle, the proofs of confirmation and confutation; and an end, the conclusion (263-75). Printed persuasion more often demon- strates this organization than oral media, which allow the speaker’s prepared approach "to dissolve under the exigencies of the moment" before an audience (266). Persuasive style relies on its medium to sway its audience and support the persuasive tendencies of logic and organization. The medium of discourse may contribute a strong per- suasive influence apart from the content of the message (281-83). A repetitive style also supports the persuasive tendency (284). Per- suasion distinguishes itself from science, information, or exploration in its high level of redundancy. 29 Persuasive Discourse: Logic Persuasive discourse develops its logic along the four lines described by Aristotle in his Rhetoric. In Kinneavyan terms, these are the "encoder proof, reality proof, decoder proof, and signal proof," or, in traditional terms, "the ethical, logical, and the pathetic proofs" and the "rhetorical style" (237). The encoder or ethical proof is the argument "from authority" or "character" (238). It first aims to establish the encoder’s "good sense" by communicating the writer or speaker’s "ability to make practical decisions, to choose the proper means to achieve an end"; second, his "good will", by demonstrating the value of his intentions toward the audience; and third, his "good moral character," by establishing his sincerity. Kinneavy cites, as exem- plars of the encoder proof, modern political candidates like Johnson, Goldwater, and Nixon who attempt to build their images through speech- making. The decoder or pathetic proof depends on arousal of the appropriate emotions in the audience: emotions which "precipitate action" (241). This proof thus depends on the speaker’s ability to arouse the emotions an audience holds in common: its general religious beliefs, cultural and social values, and psychology (244). For example, Roosevelt's reference to the American public as "my fellow Americans" aims to arouse their sense of common identity (233). The reality or logical proof relies on the "seemingly" rational argument for its force (245). Kinneavy explains that current rhetoricians often 30 call syllogism an example of the logical proof when, in fact, syllogism belongs to scientific logic. Syllogism relies on deductive-inductive logic--in contrast, the "logical" proof, as it appears in persuasive discourse, relies only on the decoder’s notions about what seems logical. The "logical" proof need not accurately draw inferences-~it need only create the impression that it is accurate. As tools, the logical proof employs the "topics" or "stereotyped arguments" which have a ready-made place in the minds of the populace (245); and examples and enthymemes, the "watered-down" forms of induction and deduction, respectively, that may appeal to a popular audience (249). Persuasive Discourse: Organization and Style The traditional Ciceronian argument has seven parts: "the en- trance, narration, proposition, division, confirmation, confutation, and conclusion" (264). These Kinneavy reduces to three divisions: "entrance and narration" (266-68), the proofs of "confirmation and confutation" (268-72), and the "conclusion" (272). The entrance serves, first, "to introduce the subject and make clear the end and object of the speech," and, second, to engage the attention of the audience (266). For instance, Roosevelt’s First Inaugural Address begins by introducing the general sentiment he wishes to convey: that America can confront and control prevalent conditions. Roosevelt calls attention to his candor in expressions like "my firm belief" and "I am 31 convinced" and engages his hearers’ sense of patriotic unity in the assertion "the only thing we have to fear is fear itself" (228). The narration supplies background necessary for understanding the issue at hand and begins to develop the ethical argument and emotional appeal. Roosevelt reviews America’s current material difficulties and asserts that he shares these dilemmas with all Americans: "we face our common difficulties." He appeals to America’s sense of crisis by referring to "dark realities of the moment" (228). Together, the entrance and narration prime the audience for understanding and accepting the argument. The confirmation and confutation constitute the body of the argument, respectively, the assertion of the speaker’s own position and the discrediting of the opponent’s. Roosevelt discredits two argu- ments: that "incompetent and stubborn" management have caused the crisis and that traditional solutions will resolve it. To counter these arguments, he proposes his program: its "moral and economic bases," "domestic and international" aspects, and its "leadership" (Kinneavy’s commentary 273). Persuasive organizational patterns vary principally by positioning the thesis statement at the beginning, middle, or end and placing the confirmation and confutation in differ- ent relative positions. Roosevelt voices his thesis--that America can face the current crisis fearlessly--in the introduction and reasserts it in the conclusion. He places the argument of confuta- tion--the discrediting of his opponent’s solutions--before the con- firmation of his own program. The conclusion usually reinforces the 32 ethical argument, logical proofs, and emotional appeal developed through the entrance, narration, confirmation, and confutation by reviewing issues the argument has raised (272). In his conclusion, Roosevelt again emphasizes his "unity" with the American public, vindicates the present democratic system, and confirms America's ability to meet the crisis through "vigorous action" (231). The style of persuasive discourse "is an immediate corollary of the nature, logic, and organizational components of persuasive dis- course" (275). Rhetorical style works with the general persuasive aim by reinforcing the ethical, pathetic, and logical arguments. Roosevelt builds the pathetic argument by arousing the emotions his audience holds in common--with the "recurrent symbols" corresponding to the "current political myth," for example, "nation," "President," and "Congress" (Kinneavy’s commentary 294). In a traditional Aristotelian context, style consists of four virtues: clarity, "the use of natural language and the use of metaphors" (276); dignity, the use of figures of speech and ornamentation; propriety, the gauging of stylistic level--grand, middle, or low--to the persuasive purpose; and correct- ness, grammaticality and good usage. Kinneavy particularly identifies Roosevelt’s use of metaphor to sustain the "current political myth" and evoke the appropriate response from the American public: confidence in the current system. Roosevelt likens himself "to Moses and Jesus, the people of America to the faithful Jews and Christians marching to a restored temple in a promised land" (295). Persuasive style often 33 suits its place and time; its ability to affect an audience depends on this "cultural and situational context." Kinneavy explains how political and religious oratory rely on their specific contexts to achieve their effects, quite in contrast to the texts of science and literature, which are less context-dependent. Roosevelt’s inaugural address, for instance, depends on the conditions of a particular context: a period when the American people still accept the positive associations or "connotative meanings" attached to terms like "New Deal" and "leadership"--yet will accept the new denotations of these terms (296). SUMMARY: THE KINNEAVYAN MODEL This chapter has reviewed Kinneavy's model of discourse, partic- ularly those aspects relevant to this study. Kinneavy focuses on texts themselves rather than authors or their audiences as the guides to aims of discourse. Kinneavy describes the nature, logic, organization, and style of four aims of discourse: reference, persuasion, literature, and expression. He describes two kinds of discourse with particular appli- cation to this study: reference and persuasion. In each case, he shows how the logic, organization, and style work together to support the overall nature of the discourse. 34 PART II: THE KINNEAVYAN MODEL APPLIED T0 SOFTWARE WRITING AT LEAR SIEGLER, INC./INSTRUMENT DIVISION Kinneavy’s model becomes an important resource for this study by placing the relationship between author and audience in a larger context: the aims of discourse. The chapter will now apply Kinneavy’s model to these texts, first, to discover their aims, and second, to demonstrate the connection between these aims and writers’ concepts of audience. It will show that the logic, style, and organization of each text embody both an aim of discourse and an associated relationship between author and audience. The chapter will use Kinneavyan terms to describe the proposal, the specification, the test document, and the user document, in that order: the order of their development in a customary software life cycle. The chapter will show that the proposal is persuasive discourse, the specification and test document are scientific discourse, and the user document is informative discourse. For each category of writing, it will demonstrate how the logic, organization, and style of the text support its overall aim. The chapter will also describe the relationship between the author and the audience of each form implied in its aim. THE PROPOSAL The following analysis examines one proposal from Lear Siegler, Inc./Instrument Division (LSI/ID) as a typical example of its genre. 35 The size and scope of this proposal are limited in comparison to those of proposals for the largest software projects, but its discourse characteristics are nevertheless typical of proposals for large projects. This proposal, like most produced at LSI/ID, includes the work of many authors who set forth a project too large and complex for one author to describe it. The proposal is the first major effort of writers involved in a software project. Like all writing in such a project, it is a group activity: often, a different writer takes responsibility for each section in the proposal. Writers receive their respective assignments to sections or chapters at an initial meeting where the lead writer, a vice-president or other high-level manager, presents the prospective customer’s Request for Proposal. The term "customer" refers to the company or military branch which has,submitted this request. The proposal’s organization follows the classical model of persuasion that Kinneavy describes. The Executive Summary serves as an entrance and narration to "introduce the subject and make clear the end and object of the speech"--to convince the customer that LSI/ID can competently produce the proposed system (Kinneavy 266). The middle reinforces the impression of technical reliability introduced in the Executive Summary (the entrance) and reasserted in the final "Manage- ment" section (the conclusion). The middle smoothly bridges the beginning and end: it buttresses the impression of a competent company by intelligently answering the customer’s queries. 36 The "Executive Summary" includes the first several pages of a proposal and acts as an entrance and narration to introduce its ethical argument. The summary argues that the company has the expertise to complete the proposed project successfully by vouching for the authors’ collective and individual credentials: The Instrument Division of Lear Siegler, Inc (LSI) has assem- bled a team of highly qualified experts to perform the tasks required by the Advanced Graphics Avionics Display System (AGADS) program. The team consists of the Spectragraphics Corporation--a premier commercial high-speed graphics house; LSI’s Astronics Division--an internationally known flight control house with flight safety expertise; Professor David Fisher--a nationally known expert and NSF-sponsored re- searcher in very high-speed computer architecture and devices; and the Instrument Division of LSI--an interna- tionally known avionics systems house with expertise in Tactical Flight Management Systems and pilot/vehicle inter- face design. (Lear Siegler, Inc./Instrument Division, Advanced Graphics Avionics Display System (AGADS) Prgposal 59 the Avionics Laboratory (AAAT-l) 9f AFWAL i) The Executive Summary incorporates the ethical argument by developing a positive impression of the proposal’s authors, the first architects of the proposed system. The summary thus affirms its authors’ "good sense," the "manifest ability to make practical decisions" (239), the first component of the ethical argument, by vouching for their experi- ence with advanced technology. It shows that the company has com- plemented its own qualifications to complete the proposed project: it has assembled a team including outside experts in fields specifically related to the proposed project’s goals. The Executive Summary argues for its authors’ good will, the second component of the ethical argument, by demonstrating that they 37 share the "basic aspirations" and "biases and prejudices" and "speak [the] language" of their audience (239). They assert that ”Estab- lishing the needs of the USAF user community (including but not limited to pilots) is fundamental in establishing the design qualifications for an operational graphics system" (LSI/ID, AGADS proposal i), and that the authors’ knowledge and support of the customer’s needs is their first priority. The authors then propose the Advanced Graphics Avionics Display System (AGADS) as the means to determine these needs: "AGADS will be used as a tool in establishing these requirements by prioritizing the usefulness of postulated display formats, information content, and other pilot/machine interface designs" (i). In other words, the proposed system will investigate the usefulness of certain displays, information, and hardware configurations by simulating actual flight and accurately assessing users’ "biases and prejudices": ...the results are meaningful only if AGADS is driven by a simulated world that represents the type of threat informa- tion, status data, trajectory and attitude guidance in- formation, and pilot decision-aiding data that will be present in the time frame of the Advanced Tactical Fighter. (i) The authors imply their agreement with the prospective customer’s value scale: they measure the proposed system’s worth as a direct function of its ability to accurately simulate tactical flight conditions of the future. And they use jargon of the field the customer shares, e.g., "pilot/machine interface," "trajectory and attitude guidance informa- tion," and "Advanced Tactical Fighter." 38 The Executive Summary implies the third element of the ethical argument, "good moral character," by demonstrating that its authors are "trustworthy" (Kinneavy 239). It vouches for their technical relia- bility: ...we are in a unique position to provide this simulated world to the USAF through our Tactical Flight Management (TFM) experience. Since we designed, developed, and pro- grammed the TFM simulation, adapting this simulation and hosting it on a VAX-11/780 and HP-9000 represents a minimum risk effort. We have extensive experience in use of VAX-11/780 and are currently programming the AFFDL HP-9000 with an Integrated Flight Trajectory Control (IFTC) computer program. (i) The authors’ collective experience supports their reliability. Their expertise makes the proposed use "a minimum risk effort." The authors thus conclude that their past personal involvement with the proposed technology insures their reliable approach to the project at hand: The "team we have assembled, our technical approach, and our program plan offer the best possible alternative for meeting the technical and schedule requirements of the AGADS program" (iii). The "Technical" body of the proposal usually includes 50 to 100 pages--close to half of its total pages--and demonstrates the proofs of confirmation and confutation. The technical body confirms the argument that the authors and the organization they represent, LSl/ID, have the tools and technical competence to complete the proposed project; it anticipates and confutes any doubts the readers may raise concerning these tools and technical credentials. The technical body begins with its own entrance and narration, a paragraph which serves "to introduce 39 the subject and make clear the end and object of the speech" by de- scribing the problem the authors propose to solve: This technical part of this proposal describes how Lear Siegler, Inc./Instrument Division will manage the technical aspects of the tasks identified in the Request for Proposal from AFAL which is entitled ”Advanced Graphics Avionics Display System." (3-i) This opening statement of the technical body states the company’s competence to accomplish the proposed task and thus introduces the proposition the proofs of confirmation and confutation will support. The technical body then confirms its opening statement by asserting that the company has the necessary hardware to complete the proposed project and can readily develop the proposed software with proven methods. The technical body summarizes the hardware that LSI/ID now has or can make available for the proposed task: memory technology, processors, and "Video Output," in other words, the tools necessary to store, generate, and display images on a screen (4-5 and 4-7). Throughout the technical body, the authors describe how each hardware component the company can provide will accomplish the proposed task. For instance, the System Processor will manage "all system resources," interface "with the local graphics peripherals," and accomplish "the advanced diagnostic functions" (4-7). In other words, this processor that LSI/ID will provide can manage and coordinate system memory, other processors, and video display techniques so that these components work together smoothly. 40 After asserting that the company has or can develop this hardware, the technical body outlines the methods the company will use to develop the proposed software: The company will use proven methods of documen- tation to accomplish the proposed software design, primarily, Struc- tured Analysis and Structured Design, methods that produce "accurate, understandable" texts (4-18). (The section of this chapter entitled "Specifications" will describe these methods in some detail.) The authors also anticipate and confute one possible objection to their avowed expertise: that they may not be able to account for system failure. The authors explain how the "Ground Maintenance Diagnostic Computer Program" will "be loaded into the System Processor...to isolate most hardware failures in the Graphics Engine and Applications Computer to the chip level" (4-17). The proposed software package will diagnose faults in the hardware down to the level of individual silicon chips. The technical body next develops the pathetic, or "emotional," argument by stirring the reader's acceptance: following the outline which the customer’s Request for Proposal suggests. In this context, the emotional argument strongly relies on rationality--on the authors' ability to show that they work in the customer’s best interest. Early in the technical discussion, the authors state that "the following sections of this proposal are a paragraph-by-paragraph response to the Statement of Work of the RFP [Request for Proposal]" (AGADS proposal 4-3). Inasmuch as the authors’ statements address the customer’s Request for Proposal, they appeal to his self-interest. 41 In a closely associated way, the technical body develops the logical argument by appealing to the customer’s sense that he is an informed reader. The authors describe the proposed program throughout its phases: procurement of hardware, design and coding of programs, and testing and maintenance of hardware and software. The program is as yet tentative, so the description has a limited correspondence to present reality. The authors may not accomplish the program in the exact manner which the proposal describes if technical obstacles dictate revision, but they present the program in a straightforward, sensible, and thorough manner which implies the customer’s good sense. The authors present the tentative description with a degree of detail that identifies the reader as a qualified judge of technical merits; for instance, they include an example of their attention to abnormal system conditions as well as usual system functions, of their ability to account for power failure by insuring that the necessary memory ("EEPROM’s" or Electronic Erasable Programmable Read Only Memory) survives such a condition: The Application Processor may have up to IM words of RAM address space if the Fairchild F9450 microprocessor, which executes the 1750A ISA, is used. This memory, like the System Processor, will be populated with both EEPROM’s and RAM. The intent of using EEPROM’s is to retain flight- critical display information in the event of a temporary power or systems failure. This application of non-volatile memory will enhance flight safety and overall system relia- bility if a system restart is required. (4-11) The example is conditional (e.g., "...if the Fairchild F9450 micro- processor...is used"), its correspondence to reality qualified. But 42 the example implies an informed reader, one who can appreciate its technical thoroughness despite its qualified correspondence to present reality. The style of the proposal’s technical body supports both ethical and pathetic arguments. Though the technical body avoids reference to personal agents with the passive voice ("Every effort will be made to..."), it uses the subject "we" to identify the proposal’s authors, whose credentials the Executive Summary has affirmed in its ethical argument, as the reliable authorities who present the technical details (LSI/ID, AGADS proposal 4-11). The style of the technical body also addresses the customer’s self-interest, inasmuch as the procuring agent identifies with the tactical fighter pilot, by using action verbs like "operate" and "survive" to characterize the pilot’s activities in relation to the system. The technical body describes those actions that involve the pilot’s actions in conjunction with the system by using these verbs to accentuate his involvement in its operation. The organization and style of the technical middle support its logical proof. To avoid emphasizing negative possibilities, the authors embed the argument of confutation within the argument of confirmation. The authors anticipate and confront possible objections to the solution they describe, for instance, the objection that their goals are unattainable within a reasonable time framework, and they relate the order of goals ("phases" or "milestones") the project will attain to represent the tentative timetable as a reasonable plan. The 43 argument of confirmation continually restates the thesis "WE ARE READY," the final sentence of the Executive Summary, and demonstrates the redundancy characteristic of persuasive style (284). The authors repeatedly assert their choice of an appropriate base system: "Our selection process [in locating a suitable graphics system manufacturer] was exhaustive" (4-2); the chosen system architecture "... provides an excellent basis for answering the critical design issues surrounding the graphics display techniques" (4-11); "The modulator architecture of our baseline approach provides an excellent mechanism for investigating a wide range of hardware configurations" (4-12); and "The baseline graphics machine provides a viable starting point for meeting overall AGADS requirements" (4-14). The authors continually praise their chosen approach to software development: "Our software development methodologies combine state-of-the-art requirements and design and verification techniques with sophisticated supporting tools and powerful computer facilities to produce high-quality software" (4-18); "...we foresee no technical problem with using either of these comput- ers [VAX-11/78O or HP-9000] for the host" (4-23); and "Our baseline approach is the result of preliminary definition work performed with our teammate, Spectragraphics, utilizing their System 1500 and graphics utilities" (4-27). The technical discussion reiterates one argument: that the authors have thought out and planned for all elements of a system to meet the requirements outlined in the customer’s Request for Proposal and that they are ready to address these requirements when they implement the proposed system. 44 In a sense, the technical middle demonstrates aspects of informa- tive logic. But Kinneavy shows how informative logics--like factuality and comprehensiveness--may reinforce a persuasive aim (253-55). He explains that "’facts’ in persuasion are put to work to prove a specific thesis," that "facts which could do a disservice to the cause must be either concealed or minimized, and facts which tend to support the cause must be magnified" (253). The presented details achieve only those levels of factuality and comprehensiveness that serve the argument at hand. Thus the AGADS proposal carefully presents the facts adhering to the case of a power failure: "In the event of a possible systems failure, the AGADS will be connected through a telephone modem to the Spectragraphics computer that contains the special diagnostics software" (4-52). The phrase "In the event..." and the modifier "possible" add double emphasis to the exceptional nature of a power failure: the proposal describes the system’s operation in this undesir- able situation to provide comprehensive information but discounts the likelihood of this event. The proposal’s final section, entitled "Management," reinforces the arguments introduced in the Executive Summary. The final section repeats the ethical argument, or argument from "character," of the Executive Summary. First, the final section vouches for its authors’ "good sense"--their technical expertise--by summarizing the credentials of proposed managers, who include the authors, in resumes. For each manager, the "Management" section provides a detailed summary of 45 educational credentials, work experience, professional affiliations, awards, and publications. Second, the final section supports the "good will" of the pro- posal’s authors and all project personnel by reaffirming the "basic aspirations," "biases and prejudices," and "language" they share with the customer (Kinneavy 239). The authors have developed these common aspirations through many past endeavors. For instance, principal staff from the Instrument Division of Lear Siegler have conducted related research--"Integrated Flight Trajectory Control Studies" and "Elec- tronic Moving Map Evaluation"--under several civilian and military sponsors (9-5 and 9-6)v Supporting staff from the Astronics Division of Lear Siegler have completed "advanced flight control" studies and developed "flight management systems" for other sponsors whose inter- ests in tactical navigation parallel those of the US Air Force (9-7). The proposal’s authors and other project personnel have also deve10ped "biases and prejudices" similar to the customer’s. These authors rec- ognize the importance of "integrated circuit fabrication technology," which will permit development of increasingly complex computer chips in the 19803, and the necessity for "proprietary integrity," the zealous withholding of information sold to one customer from other potential users (9-6 and 9-7). To communicate these qualities of project per- sonnel, the proposal's authors use the jargon they share with the customer. They employ the terminology of tactical flight technology, for instance, "MIL-STD-1553 bus," an interconnected path for system communication that conforms to Military Standard number 1553. 46 Third, the final section reaffirms the "good moral character" of authors and all project personnel, the third component of the ethical argument, by establishing that they are "sincere and trustworthy" (Kinneavy 239). They intend to use reliable equipment and facilities (7-1), extensive project documentation (9-1 through 9-4), established control procedures (5-4 through 5-9), and an effective company organi- zation (5-1) to insure quality. The Aerospace Development Center in Grand Rapids, Michigan hosts sophisticated software on advanced main- frame computers; the planned documentation includes many items of "deliverable data" (9-1); the control procedures require advanced analysis of cost and weekly reviews to prevent cost overruns; and the organization encompasses top-level company officials who will become personally involved in the proposed project throughout its phases. Near the beginning of the final "Management" section of the pro- posal, the authors summarize these resources to suggest their sincere aim and trustworthy ability to complete the project: Program control is maintained by the daily managerial acti- vities of the Technical Director. He is aided by the computerized cost analysis, by weekly program status reviews by the cognizant program engineers and their normal line organization department and division managers, and by formal required documentation. (5-7) The proposal writers suggest that they and other members of the proposed project staff will smoothly integrate all possible measures to insure quality and timely production. They will use the available equipment and facilities, documentation, control procedures, and 47 company organization to complement one another in a manner that best serves the customer’s interests. Throughout the Executive Summary, technical body, and final management section, this example of a proposal from Lear Siegler, Inc./Instrument Division demonstrates many aspects of Kinneavyan persuasive discourse in a unified manner. First, its logic centers around the components Kinneavy describes, particularly, the ethical argument, or affirmation of the authors’ ability to complete the proposed project, but also the pathetic and logical arguments, or appeals to the customer’s emotions or values and to the nature of the problem at hand. Second, its organization follows the classical model Kinneavy describes: entrance and narration (Executive Summary), introducing the ethical argument; middle (technical body), developing the ethical, pathetic, and logical arguments; and conclusion ("Manage- ment” section), reaffirming the ethical argument introduced in the entrance and narration and supported throughout the middle. Third, its stylistic traits support the ethical, pathetic, and logical argu- ments--supporting appeals to the proposal authors’ reliable authority, the customer’s self-interest, and the nature of the task at hand. SPECIFICATIONS Specifications normally include two parts: the Part I or require- ments specification and the Part II or design specification. Each part often includes many volumes. For instance, the Part I and Part II 48 described below include 15 and 30 volumes. Volumes average several hundred pages in length. The Part I first states the requirements the system must meet to reflect the customer’s requests. Its writers attempt to address the customer’s written statement of requirements-- the Specification Control Drawing (SCD). They must often talk with the customer throughout the writing process to clarify the intent expressed in the SCD. In later revisions, the Part I revises these requirements to incorporate feedback from the customer, designers, programmers, and testers. The Part II describes the design of a system to satisfy these requirements in a form programmers can translate into code. To determine the aims of these specifications, the following discussion will look at the tools used in contemporary Part I specifi- cations by drawing examples from a particular Part I. The discussion will examine analogous tools used in contemporary Part II specifi- cations by drawing examples from several Part II’s. Traditionally, the writers of the Part I specification employed narrative prose and ad hoc diagrams and charts as their primary and secondary tools. Then, in 1978, Tom DeMarco, a consultant on systems analysis, developed the data flow diagram and Structured English as complementary parts of an approach to analyzing and documenting requirements for relatively simple systems like those involved in banking transactions. In 1982, Derek Hatley, a Systems Analyst at LSI/ID, adapted these tools of "Structured Analysis" to implement the analysis phase for the Flight Management Computer System. Hatley altered DeMarco’s basic approach to 49 allow for the requirements of avionics systems, with complex control requirements and split-second timing. The examples described below reflect Hatley’s modifications to DeMarco's basic tools: the data flow diagram and Structured English (DeMarco 37-44). To complement Hatley’s work, designers at LSI/ID, who write Part II specifications, adapted the tools of Ed Yourdon’s and Larry Constantine’s Structured Design, an approach to the description of system design, to describe the design of programs that could meet the requirements outlined in the Part I. While the writers of the traditional Part II used narrative prose and flowcharts as their chief tools, the writers of the current Part II use the structure chart and pseudocode (Page-Jones 11-16, 75-79). Both the Part I and Part II specifications embody scientific dis- course and its supporting logic, organization, and style to fulfill their primary aims. These texts are "’thing’-oriented," with a focus on "formal reality," an abstraction from the "material object" or world which we perceive with our senses (Kinneavy 88, 80). For instance, the specifications abstract from the world of cockpit and flight the func- tions the computer guiding the airplane must perform. The Part I and Part II specifications organize themselves around the proof-orientation of scientific discourse by describing relationships between computer functions with deductive-inductive logic, and they adopt a style typical of scientific discourse by using specialized terminology to describe these functions several levels removed from human agents. 50 The Part I uses the deductive-inductive logic of scientific dis- course to demonstrate "the truth or validity of a referential assertion with as much certainty as the techniques of [this] given logic can achieve" (Kinneavy 108). The Part I for the Flight Management Computer System shows that the system must meet certain requirements to accom- plish efficient flight management. The specification first uses a ”context diagram" to demonstrate that the computer system (the central "bubble" in Figure 1) must interface with the external entities (the peripheral boxes) (Lear Siegler, Inc./Instrument Division, System/ Software Requirements Document for the Flight Management Computer EXEEEE 6-22). For example, it must receive data from the aircraft (the bottom box) and exchange data with the Control/Display Unit (CDU) (the top box), the crew’s main instrument for communicating with the system. The Flight Management Computer System must relay all relevant data concerning the aircraft, its location, and environmental conditions to the Control/Display Unit (CDU) so that the CDU can display this data on a screen at the pilot’s right hand. The computer must also relay to the aircraft all commands the pilot issues on the alphanumeric keyboard below the screen. The top-level data flow diagram (Figure 2) then infers five more specific requirements from the general requirement that the Flight Management Computer "PERFORM FLIGHT MANAGEMENT" (6-24): 1 MANAGE CDU & EFIS. The computer must exchange data with the crew through two devices. Through the alphanumeric keyboard on the Control/Display Unit (CDU), the computer must receive the crew’s directions; through the display screens on the CDU and Electronic Flight Instrument System (EFIS), the computer must transmit information to them. 51 INPUT DISC”. PINS. am an (2) ANLG:DIG I am mars "1 cou sex ’"DCTR DSPLYS (2) mm W“ n: Minn uu mm . m cm - :xo DATA FLIGHT ) iiiiihwmmamn wr ww an (a tan FUEL up on ma an aux um Ann as 39 I05 Ilu tux? an 1w (3) . (2) nuwwr Figure l. OTHER FINIS CLOCK Context Diagram FCC TGTS. “INC 357 W5 KP DATA. ARINC 35G HOS All INPUTS EFIS I INC 357 W5 ARINC 356 ES NAV DATA 1 FCC NCP l I - ..JL—..— L A/T DLU 52 amummwn 30am mama .N muzwwm a... ... 8...... .8. .8. 8...... .5 ...-.... ...... ...... ... a: .3... .... .853... 8... 8...: ...! ....a. \ 5...... ..8 .8. 2. £8! 8.» / . s... ...-...... 8.. ...... 8. .25.. ..8 u ...... .... .... .. ...... an. 5.82: 5.. .5 ...... l .8... . - I ...... .... 8...... z, ...... ..s... n... =1. \ 8.... . ......a ... . .... \\ ...... ...-...... ...: .58.... . ,, =3... ...... ...... a... . 8. ...... ... ...: :2... a... ...... ...... ... ......a 8... .... .9. ...... ... .22.... .S. ...... ...... .8... 9.. .88 .... 8... ... :8 :8 a: ...... .....8 2. ...... \ x .2! .288 :- ...... 3.. ....3 a... ...-o a... ...... _ .5 .... 898.8 .... ..8 _. . in: a: .33 5‘ in! 3w. .3 p3 .3355 E 63‘. Eu \\(.8 .....\ :36 ...!um E» .g .3 d as Sc sic-u / , . .08. 55:8 83¢ .5: 5i- .Eca 5:3 / ...: ...8. mac :1 ...... .22.... 2.. ...... .8. :- .3. .8 9...! .88 .... 8... .../V 3.83.... .... .... .8... ...a ...... .....a ...... ... a .3. a. 2...... :8... ...: ...... ... \ ...... .8: :- 82... ...... Sn... _. 23 .....a .... ...... ..fiux “...“... WWW“... .- i. .8. ... .... ...... Ill-I'll!" . - ...... .8. , n / ......E .8. .... 338.... . ......8 .... .88 .... ..8: a ... amyéfi... an ...... ._ .8. ... ...: 3. ... .... .8. ......a .... ...... 8...... ...... , ...... ...... .... a... .... \ 53 2 MANAGE FLIGHT TRAJECTORY. The Flight Management Computer must direct the plane’s vertical and horizontal steering. 3 COMPUTE PERFORMANCE. The computer must monitor internal and external conditions affecting engine and aerodynamic performance, including throttle and drag. 4 PERFORM NAVIGATION. The computer must determine the aircraft's present position, direction, and velocity. 5 PERFORM BIT. The computer must perform built-in test, that is, monitor its own functions. This exemplifies Kinneavy’s description of deductive logic: it shows that the particular requirements "inferred" are "implicit in the premises"--the general requirements (109). The data flow diagram represents the system’s particular five functions inferred from the general process in the context diagram. The Part I specification demonstrates deductive logic by beginning with the most general and proceeding step-by-step toward the inferred specifics. After the Part I represents the system’s requirements in the context of its central computer and peripherals (Figure 1), it portrays the computer's internal requirements at a general level involving five main functions (Figure 2). Later, in five data flow diagrams, the specification represents the requirements of each main function in the context of its particular subprocesses; for instance, it shows the internal requirements of process 2 in the context of the seven subprocesses in Figure 3 (6-28). And the specification continues to progress from the general to the particular by representing the internal requirements of these subprocesses in later data flow 54 ....l. .... ... ... i... 5.. .... .... 32/ anuwmwa 30am mama Hm>oAIvdooum .m unamwm \ /...... ... . ... .8. .... ...... ... ...... 22...! ... .... ...» ...... fi .... ... .5 :2 .iu .35: flu .... ...... I... In: .\\ .3 :3 g .g a! g 45 .3. as. .33 I: .38: 3.: :« =9 8.: .35.. :u .338 I .3: .3: D .u 4/ ... .8. ..B ......“ "a 25.7 ... .8 .... / .... 8.... t. .u... out... 88.. t. \ - .... ...... . 3...... ...: .... I... .... .... I. ...... .... ...... 9.... ...... .....V . i 5 .....II: .. ...: ... ...... - ..I 3... ..l ..<. z... ...... .22.»... ... ...... 2...... savanna.“ .5... ....“ . . .... . ATile... .... .... as... .... .... ...... .3. .2... .... ... \ .33 .... 3.. ..qt ... 5 ...... .... ... ... .8. ..B .2... .... ... ...: : .... 8... ...... ... .8. ..B ...... I. .2. ..I. ... ... .... ...8 .....n. 2:... ..8 / 55 diagrams. The text may continue this progression until it has repre- sented as many as ten levels of requirements. The organization and style of data flow diagrams follow their scientific logic. The organization of data flow diagrams supports the deductive-inductive logic of scientific discourse by gradually pro- gressing from the general to the particular; their "pure outline form" and abbreviated terminology of data words comprise a scientific style geared to a select group of specialists (179). In Figure 1, the data word "CDU DSPLYS" on the left-hand side of the arrow between the central bubble and the box at the top center signifies that the Flight Management Computer (the central bubble) generates displays for the pilot’s Control/Display Unit ("CDU," the top box). The requirements dictionary in the final pages of each volume includes an alphabetical listing of the data words used on the lines between bubbles in data flow diagrams and defines each data word (see Figure 4). On each page, the dictionary lists the names of data words in its left-hand column. For instance, the dictionary shows "ACT_CRNT_PHASE" at the top of the left-hand column, under "NAME." It then defines data words in the first column from the left. For "ACT_CRNT_PHASE," the dictionary spells out the definition, "ACTIVE CURRENT PHASE," at the top of the first column from the left, under "COMPOSED OF/DESCRIPTION" (LSI/ID 2-116). The dictionary thus offers an easily useable reference to any reader who needs a data word defined. In particular, it serves the writer who can refer to on-line 356 zumdowuuwm wuameufisvom m Scum mwmm .q muzwwm ... u z. ...: 1,..o ...:mm ..zmxzou n...-.o.-.~ an. ......zu 2.7.2.... ...: 52...... .2.... ... + .a.... ... ....9 .. + :=2 e. ...we + an: o. ....9 . 4 ...»..K I u u z a + moo. 2x. + ..zmo. on. ,.. ¢ .... 8.... . an. .. . . z. ...: ..mw. ,ayx. .... zamo ..o ...:m: ..zmxzau ....-...- -. an. ”amoz.:u ....-.uz- -. an. "amxmaz. ...E ..mfifis2« 2 .....c. a u ... ... m.=..> o. ..z m 9 ao...o ..3.:..=u.o.... 2 ... z..o .3.\.m. .. ... n z. amm9 ...... ... ..c ...:m: m;,, .... a. . "azmzxou ....-.az-. ... .nmoz.=u ..a.., ....-.q.-. 2.. "gnaw... «. .uvaumuaa DownhUA ac: .ovaufluaa unwauuA .au:~a> * .. :.... .a 2 .o..u.nz. . u z ..z ..z ..a..> ~ ,g;.. .. ... m u ......mzoo maze...< 2 e.gz. has... ... .e;;. .u.... u. ,.- ... u z. ...: ....z. ..o «magma .hzmzzou mwouu>nzun o * z ... ,aamm»...zm. .....2..> . ... m u 2 mm.:. panama. m>.~u< 2 mm.=.n...uu.u. o ... ”womam.m. oz. .22: 2.. u zo.....u.mn mzm.zo..u.a ..zm:m..=om. 57 drafts of the dictionary while creating data flow diagrams with con- sistently spelled and defined data words. The requirements dictionary makes a text organized around deduc- tive-inductive logic more easily useable by writers and readers. The dictionary allows users to locate specific system requirements without searching the entire body of scientific proof. The cross- reference helps analysts, designers, programmers, test engineers, and the customer to read the Part I selectively in order to identify or recall specific requirements. Like the data flow diagram, Structured English--the secondary tool of the current Part I specification and supplement to lower-level data flow diagrams--demonstrates a deductive logic and supporting organiza- tion and a style aimed at a specialized audience. It implies the logical relationships of a computer system by using a specialized diction halfway between Standard English and code--a limited vocabulary of imperative verbs and data words--and arranging phrases and clauses on a tab grid. For instance, Structured English uses the imperative "Do..." and adverb "Next..." to imply sequence: Do X Next do Y Next do Z (Hatley 2-17) " and "Next..." on In this instance, the placement of "Do...," "Next..., the same tab as well as their implicit significations suggests a sequence of actions the system must take. Structured English thus performs a task which data flow diagrams cannot: it states requirements 58 of sequence. Structured English may perform another task impossible for the data flow diagrams by implying conditional requirements: If ON GRND or TAKEOFF or CLIMB Set CRZ_DIST = TRIP_DIST_DES DIST then set CRZ_TIME = CRZ_DIST7CRZ_SPD (2-17) H The indentation of the imperative "Set... as well as the implicit signification of "If..." suggests the conditional relationship. By describing such conditional requirements, Structured English furthers the scientific logic of the Part I specification. It shows how the premise of a given condition implies the conclusion of a resulting requirement within the deductive-inductive structure of the specifi- cation. Like the writers of the Part I, the writers of the Part II use the deductive-inductive logic of scientific discourse to demonstrate "the truth or validity of a referential assertion with as much certainty as the tools of [this] given logic can achieve." In the Part II for the Flight Management Computer System, they demonstrate the validity of certain design characteristics for the performance of efficient navigation. The writers of the Part I use the data flow diagram and Structured English as tools; to continue the process of system speci- fication begun in the Part I, the authors of the Part II use analogous but different tools: the structure chart and pseudocode. The structure chart is a graphic portrayal of system design that represents the relationship between top- and lower-level processes in the system. Pseudocode is a prose-like description of logical relationships within individual processes. 59 Designers compose the structure chart with the same scientific logic as the analysts who create the data flow diagram. In a current specification, they use structure charts to show how higher-level computer processes use lower-level subprocesses. For example, Figure 5 demonstrates how two "Keyboard Managers" near the top rely on a row of subprocesses along the bottom (LSI/ID, Software Design Specification for the Flight Management Computer System 5-16). The managers (KYlMGR and KYZMGR) interpret the crew’s keystrokes on two Control/Display Units, one at the pilot’s right hand and the other at the copilot’s left hand, through "KEYPRC," or "Function Key Processing" (bottom right). Like the authors of the Part I, the designers who write the Part II specification begin with a top-level process and proceed step-by-step to its subprocesses. From the premise that the system manages the keyboard, they draw the conclusion that the system inter- prets the crew’s keystrokes. In this "process of inferring conclusions from premises," they satisfy Kinneavy’s definition of deduction (116). Kinneavy’s scientific logic encompasses all such movement from premises to conclusion by inference, not only the inference from the general to particular. The authors thus exercise the deductive logic of sci- entific discourse in the structure chart’s movement from higher- to lower-level process. In the "Structure Chart" these designers develop a style typical of scientific discourse. They use a numerical outline format (e.g., "CHART 2.3.1") and the scientific shorthand of data words (e.g., 6O uumnu musuosuum .m ounwwm ..n.~ pita MEL {2 I ...”...zsihsif as... 5.999% FMV ...... Em .... 5.3 .... .flafimH WM...” HM. when. ./L..§i§5. I i. is: 61 KYIMGR, KYZMGR, and KEYPRC) that appeal to their restricted audience. The outline form reinforces the leveled organization of the speci- fication by indexing the relationships between levels. For instance, the label "(2.3.1.1)" below "Function Key Processing" implies its derivation from "2.3.1 Keyboard Managers." The data words assist one audience in particular, the programmers who must translate the design into code and who need a discrete name for every process in the leveled organization. Like the requirements dictionary in the Part I, the design dictionary in the final volumes of the Part II includes the most recently accepted spelling and definition of each data word. The design dictionary provides a cross-reference to modules using each data word for designers and programmers who approach the specification to locate specific facts about system design. Like the requirements dictionary, the design dictionary allows users to read the specifi- cation selectively. The overall logic, organization, and style of the Part II specifi- cation develop around the hierarchical relations of the structure chart. The specification subdivides the system into hierarchically ordered "functions," "packages," and "modules." The system itself is the highest-level boss which invokes its several functions. Functions, in turn, invoke their subordinates, the modules, through a chain- of-command including both packages (below functions and above modules on the hierarchy) and other modules. Primarily, the specification uses 62 structure charts to represent this hierarchical chain-of-command. The specification uses prose to this end secondarily, only to refer the reader to the appropriate structure charts: 3.5 Compare Function The Compare Function is composed of the following [packages]: CHART TITLE Compare VHF Navaid Data Compare NB Navaid Data Compare En Route Waypoint Data Compare Hold Pattern Data Compare Airway Data Compare Airport Data Compare Terminal Waypoint Data Compare ILS Data Compare Runway Data Compare Terminal Procedure Data Compare Company Route Data U1UIU'IU1U'IU1UIU1MU1M \IO‘\0\O\O\O\U\J.\UJNH LJ'IJ-‘th—A (LSI/ID, Software Design Specification for the Navigation Data Base 5-7) This sparse description of the Compare Function simply refers the reader to the appropriate "CHART” for relevant details concerning its subordinates: the "packages" listed in the "TITLE" column. The speci- fication may also use prose for a slightly more expansive purpose--to clarify the relationships between a boss and its subordinates: 3.5.1.3.1.4 Return conditions. The current and previous cycle customer data will have been compared, and the resulting effective data will reside in the current cycle customer directory. (5-10D) Here the designer describes the conditions under which the subordinate ceases to act and returns control to the routine that called it: its boss. Yet the designer indicates only the general status of data as the module completes its processing. The writer of the Part II 63 specification thus accomplishes a general representation of the program's hierarchical logic primarily with the structure chart and only secondarily with sparse prose. For the detailed representation of this logic, the designer uses pseudocode, a limited diction of data words and logical tags easily translated into code. Pseudocode includes more detail than the Struc- tured English of Part I specifications because it describes a full system design rather than basic system requirements: it outlines the deductive logic of the actual program. For instance, in Figure 6, it infers "Set... imperatives from conditional "If...then" clauses (Software Design Specification for the Flight Management Computer System 5-122). From the premise that the "control transferred indicator is no" (top), it draws the conclusion that the program should "Set scratchpad run to yes." The organization of pseudocode supports its logical structure by arranging conditional and imperative clauses on tabs. For instance, the "If..." clause at the top of the page covers all of the additional conditional clauses and imperative statements beneath it as far as the "End if..." at the margin directly below it two-thirds of the way down the page. The organization and style of the Part I and Part II specifica- tions support their deductive-inductive logic and overall scientific aim: proof. The primary tools of these specifications--the data flow diagram, Structured English, and requirements dictionary of the Part I, and the structure chart, pseudocode, and design dictionary of the Part 64 If the control transferred indicator is no then Set scratchpad run to yes ‘fi; Set wait for done indicator to yes gfififififi;_ If the function key code is for a mode control key then “5* Set the valid function key code to the function key code Set control/display run to yes fifig ____ If the scratchpad status is delete displayed then gfii'ggflmm Set the delete displayed indicator to yes fifigggfiflfif End if -fl§$¥ Else if the function key code is for a line select key then '" Perform the line select hey processing (call LSKXPR) Else if the function key code indicates a scratchpadfiéfiifiusgchange then If the message class is class 1 and scratchpad sifitgi is auto scratchpad clear then W§g_ Set the valid function code to clear button """ Set the control display run indicatorfito yes End if ,,§fififfi_ If the message as data indicator is yes then”@§& If the scratchpad status is empty then Set the valid function key code to clear Set the control/display run indicator to yes Set the message as data gaaggagg: to no Set the hold at display indicator to no End if 'V” End if is. End if If the alert advisory message request“i§ invalid delete or invalid entry then .' ' Perform a request messageafiith the alert/advisory message request (call HSG (message nunbérlgfiggg- End if ”Q? If the scratchpad status is indicator are yes then .3~ A? Set the local controlfigrahsfer indicator to no Set the global control tifigsfer indicator to no Set the scratchpad run indicator to yes Set the wait for done indicator to yes Set the controlfdisplay run indicator to yes Set the valid ffinctifip key code to the function key code If the functionfiheyg£6de is scratchpad status change then Set the line sélect key action to test complete , o done and the (global or local) control transfer Else Setgfiyg line seleCt key aetion to select Page End 1 End if "fifiir port number (KYNRPY)) Figure 6. Pseudocode 65 II--support this proof-orientation in a unified and coherent manner. By using a hierarchical organization that reflects deductive-inductive logic and the abbreviated terminology that appeals to a select group of analysts and designers, these tools support the logical derivation of particular requirements and design characteristics from more general system traits. THE TEST DOCUMENT The next major division of documentation in the project cycle normally consists of three phases: the Test Plan, Test Procedure, and Test Report. Often, a Test Plan, Procedure, or Report restricts itself to a given area of a computer system, so that its contents do not exceed one volume (400 pages). For instance, the following examples concern testing of the Alternate Navigation Control/Display Unit (ANCDU), one component of the Flight Management Computer System, not the entire system. The ANCDU is a Control/Display Unit with built-in hardware and software that allow it to navigate the plane should the main computer system fail. The Test Plan explains in advance how testing will address "each individual requirement from the SCD [Speci- fication Control Drawing-~the customer's statement of requirements] that is applicable to system test" (LSI/ID, System Verification Test Plan for the Alternate Navigation Control/Display Unit 5). The Part I has translated the customer's SCD into a statement of requirements 66 useful to the writers of the Part II. These writers of the Part II have described the design characteristics that will satisfy these requirements for the benefit of the programmers who must translate the design characteristics into code. Once programmers have done their job, test engineers must assess whether the finished software system satisfies the customer's requirements as stated in the SCD. The Test Procedure describes how test engineers will assess the system’s conformity to each relevant customer requirement. This document may list the procedures testers will use to meet the customer's require- ments in one column of a table and the requirements themselves in another (Figure 7). For each test case (first column from left), appropriate input keystrokes on a Control/Display Unit (second column from left) bring a resulting display or table and, in so doing, fulfill the customer's requirement (far right-hand column). The third row indicates that key 5R should result in display b (bottom) to address the customer's requirement of paragraph 3.4.1 a in the Specification Control Drawing (LSI/ID, System Verification Test Procedure £2£ the Alternate Navigation Control/Display Unit 89). In this instance, the tester should select the appropriate display on the Control/Display Unit and verify that it matches display b. This outcome satisfies the customer’s requirement in the listed paragraph of the Specification Control Drawing. Finally, the Test Report completes the end toward which the Test Plan and Test Procedure have advanced by summarizing the system test in laboratory simulation. It shows how the Test Procedure worked out in practice and indicates how test engineers may change the 67 mmme ”~me .m muswfim v hogan“: o hogan“: a hogan“: m undo-ya . . . . _ _ _ . 3 _ 6239:--m5 ..... 85v _ 3 .3 n 3.3 E--m§ ..... 83v " .3 a... “ 2:3 Ea--mx7mm§8§v “ .3 .3 u 9.3: n .3 . . an _ agoammozuv . an an . . an an _ accommomuv _ an an _ x>¢z azuauv . a. . oeaaauaoa «essay-"\aauea _ _ «no use on _ _ _ _ _ _ as. <= men uuuaom a an .~ an: —.3 mum one .3 ~._.n "on aaaaao uzaz< assuage an «an-u o~\a~u use m«-¢~.go .sa-oua >~po annex 6R Q saIGNT ADJUST ° nae—:1- 0 PAGE SELECT KEYS EIEHEIEIEI- mar... {:RLUNCIATOR ' ®® (3) E. IE] E [33 £®©©Emmmm @CDQEIE [BENZ] "“M ®@@,EIUEIII NUMERIC KEYS ALPNA KEYS Figure 8. Control/Display Unit mes aITE FMCS BITE CAN BE USED FOR FAULT ISOLATION AND VERIFICATION OF TIE FMCS AND INTERFACINO LR (CLOCK. DAA. DADC. DECS. DME. FUEL SUWATION WIT, IRS. MCP. VORI. FNCS FAILURES ARE EASILY RECOGNIZABLE. NOTE: ENSURE THAT FMC AND CDU CIRCUIT BREAKERS ARE CLOSED. - INDICATION CAUSE 0 HM: IN MIDDLE OF cou SCREEN. FMC FAILURE - FAIL ANNUNCIATOR LIT ON cou. . FMC ALERT LIT ON FMA. . FAIL LIGHT ON FRONT OF FNc LIT. 0 CDU SCREEN BLANK. DISTORTED, CDU FAILURE OR UNINTELLIGIBLE. NOTE: IF AN FM FAILURE OCCURS. [M S BITE CANNOT E ACCESSED. HOW TO USE BITE . CHECK IF LRU IS REPORTED As FAILING USING FMCS SENSOR STATUS AND FMCS IN-FLIGHT FAULT PAGES. 0 CHECK OTHER FMS SUBSYSTEM BITE (IF AVAILABLE) FOR COMMON LRU FAILURE INDICATIONS. 0 USE TESTS AND CHECKS AVAILABLE FOR THAT LRU. 0 REPLACE LRU IF NECESSARY. 0 VERIFY PROPER OPERATION USING BITE. Figure 9. Selection Table 73 with a logic, organization, and style typical of informative discourse. The guide also attempts comprehensiveness by organizing its content to cover all instances in which its reader would employ a particular piece of software. The "BITE PROCEDURE SELECTION" page (Figure 9) Offers the user a complete menu of procedures and lists the appropriate line select key (LSK) on the Control/Display Unit for each procedure. In the booklet's remaining pages after the "BITE PROCEDURE SELECTION" page, the pocket guide describes all of the procedures in more detail to provide a comprehensive treatment of its subject. Indeed, the pocket guide provides as much comprehensive informa- tion as it might within its short span throughout its entire intro- duction, body, and conclusion. On the first page, it explains in five easy steps "how to use BITE," providing the outline for the entire procedure. On each of the following pages, the pocket guide includes warnings against a misguided procedure, presumably covering all the common errors. 0n the second page, for instance, it instructs the technician that three circuit breakers must be closed in order to use BITE. Pages 4 and 5 warn the technician against rashly deciding to "replace the FMC [Flight Management Computer]" at this point without running further tests, since a less radical solution may be in order. Page 6 warns the technician that some failures may be "intermittent" or temporary and may not require replacement of system components. The remaining pages contain similar warnings to avoid harmful, expensive, or dangerous procedures. These encapsulated warnings demonstrate 74 comprehensive attention to detail by covering each major instance in which a technician may harm the computer system. The dominant informative logics of the BITE pocket guide, as of all highly-technical user documentation produced at LSI/ID, are com- prehensiveness and factuality; surprise value plays little or no role in such documentation. In the ways the short pocket guide covers its potentially vast subject matter, comprehensiveness becomes a parti- cularly dominant logic. The guide not only offers the technician a complete menu of the procedures it catalogs in the BITE selection page; it also refers the technician to submenus available on the Control/ Display Unit. For instance, on page 11, it displays the menu for tests that verify the proper function of the CDU itself, by showing the technician two options: the "KEY TEST," to assess whether the alpha- numeric keys are properly working, and the "DSPLY TEST," to make certain that the video display function is Operable (see Figure 10). In this instance, factuality also plays a role: the technician may readily test whether the menu brings the associated pages to the screen, that is, whether the user document is factual. On the other hand, surprise value is weak or absent. The thS BITE Pocket Guide imparts limited new information because the mainte- nance technician has already studied a more detailed manual before entering the plane. The guide simply serves as a memory jogger to help the technician recall the outline of the detailed manual: it merely summarizes the step-by-step procedures necessary to test the functions of the CDU. The guide thus has little surprise value in the Kinneavyan 75 sense, unless the technician has not studied in advance and becomes surprised by its contents. If, as Kinneavy cautions, we should measure surprise value against "the 'current' probabilities of a group audience or individual receptor," we should assume that the technician is already familiar with the information the guide contains, and it is unlikely that the technician will find the material surprising. The organization and style of this user document generally support a Kinneavyan informative aim and its associated logics. The organiza- tion supports comprehensiveness by systematically including a great deal of the information a user is likely to need within the guide's FMCS CDU TEST 2._ FMCS CDU TEST III PROvIDES [—33 ACCESS TO THE Two cou TESTS. w F FMCS CDu TEST m? E [3 IE E] [E] (a [E E «Ev TEST DSPLY TEST> E3L:”“‘ E3 _J use FMCS KEY TEST TO USE FMCS DSPLY TEST TO VERIFY CHECK CDu KEYS FOR CORRECT CHARACTERS ARE DISPLAYED PROPER pPERATION. ON ALL POSIQONS OF CRT. —FHS— -T_ST---- I - E] IN! ET‘ECSC'L‘EYCIREZSBES‘“ E‘j |r2315fisrzf€iajaszskv DIRLEGOEPHOLPROEXE as TQITIE;IOI-! IL NI Fxx ABCDE IR 8'2 SE 8': 93.4.51er ‘3 .... W 2* E ”:23... ..:;;:;..s.:; E‘ It $35 ”“533 3,3 "“9 ‘3 :::;;9;.:;"':‘;'314r;:! SPARE KEY ,“,u, [u I .3 E] 9.“.--33 ..... z. ’3--- “ / NOT TESTED E x ~33” Q’j‘gfig‘fi ‘L. .’_ r n «L no E KEYPEKEYKEINOITCOATTES VALID E PORSVUVVIT:ECIJE}E’OI;31;ET *—/ chu ,1;ng9“ -E‘lfif???::::::::::::::: “ E T— Figure 10. Test Menu 76 short length. The style--with its photorealistic depiction of the displays and schematic detail of system functions--supports factuality by offering data the user may verify in practice. In these senses, the BITE pocket guide and other similar pieces of user documentation produced at LSI/ID exemplify Kinneavyan informative discourse in a coherent manner. SUMMARY By using the Kinneavyan model, chapter 1 has shown that the texts software writers produce at Lear Siegler, Inc./Instrument Division demonstrate unified purposes. The chapter has summarized James Kinneavy's Theory ht Discourse, that classifies all discourse by four aims: reference, persuasion, literature, and expression. The chapter has particularly described reference and persuasion, the two categories most germane to this study. Kinneavy's classification of all discourse by aims has provided a vocabulary to differentiate between the purposes of several types of writing. This classification has revealed a tripartite division of aims in software writing at LSI/ID: the per- suasive aim of proposals, the scientific purpose of specifications and test documents, and the informative aim of user documentation. By illustrating how the logic, organization, and style of each kind of software writing support its aim, the chapter has shown that each text embodies a unified purpose. CHAPTER 2 Chapter 2 will review the Institute of Electrical and Electronic —._—_———_————————— Engineers Transactions eh Professional Communication, the major periodical on communication in the electrical engineering field, to determine how contributors to this quarterly have described the purposes and audiences Of engineering writing, the engineering writer's audience, and the engineering writer's task. In general, from 1981 to 1985, IEEE contributors have offered much to engineering writers in the way of clarifying the concepts of purpose and audience, the nature of audiences, and the character Of writing tasks, even if they have not specifically described how purpose and audience function in the context of large-scale software projects. The Institute of Electrical and Electronic Engineers is a national professional organization that publishes over 45 periodicals in its members' fields. These fields cover a wide range, from acoustics to ultrasonics. Electrical engineers practice disciplines as diverse as cybernetics, the study of automatic control systems like the brain and electrical and mechanical systems, and geoscience instrumentation, the study of electronic devices to measure meteorological and seismic phenomena. Since the late 1950s, the Institute of Electrical and Electronic Engineers has published the quarterly IEEE Transactions eh Professional Communication to cover engineering communication. Contributors 77 78 to the quarterly have discussed engineering applications of all the language arts--writing, reading, speaking, and listening--not just the first of these, for hardware as well as software applications. This chapter will examine the most recent history of the quarterly, from March 1981 to December 1985, to relate contributors' concepts of the purposes and audiences of engineering writing to this study's focus: the purposes and audiences of software writing. These contributors include both faculty from liberal arts and technical institutions, who teach engineers to write, and engineering writers from corporate settings. Their collective attitudes thus reflect general trends in the field of engineering communication, both its academic and in- dustrial spheres. To select the sample this chapter surveys, I first studied the index at the end Of each volume published between 1981 and 1985 and listed all articles and book reviews with relevance to engineering writing, including any concerning reading, speaking, and listening that seemed relevant to writing. I partially reduced this total sample of 146 articles and 31 book reviews, all listed in the bibiography, to 132 articles and eight book reviews, by assessing the relevance of each piece to the purposes and audiences of engineering writing. I further reduced the sample by, first, excluding nine articles that focused on these purposes and audiences in the context of the engineering class- room with little relevance in the engineering workplace; second, eliminating 11 articles and two book reviews that concerned the 79 purposes of writing tools, including word and text processors, not the purposes of engineering writing; and third, excluding three articles that described the speechmaker's relationship to the audience, with little relevance to the writer's situation. By this process, I reduced the initial sample of 146 articles and 31 book reviews to 109 articles and six book reviews. I then grouped items to illustrate three ten- dencies of contributors this chapter will discuss. First, though some contributors implied that each kind of engi- neering writing involves simply-defined purposes and audiences, many developed more sophisticated concepts of the relationship between each form of writing and its purposes and audiences. Some contributors assumed that each kind of writing implies simple definitions of purpose and audience apart from its context--which, the introduction and chapter 1 have shown, may include several audiences with diverse pur- poses. But other contributors recognized that many kinds of engi- neering writing may require the writer to define purposes and audiences in a complex corporate context, though most contributors stopped short of describing just how complex these purposes and audiences may become in contexts like large-scale software projects. Second, contributors developed an expanding concept of the engi- neering writer's audience. Though many assumed that the engineering writer addresses a reader with poor reading ability or little technical background, others developed the concept of a diversified audience with varied levels of reading ability and technical expertise, if 8O considerably more homogeneous and less multifaceted than the audiences of large-scale software projects. Third, contributors expressed an expanding concept of the writer's task. Throughout 1981-85, many emphasized correct spelling and usage and clear organization and style as the writer's major and, sometimes, exclusive concerns. Yet other contributors further served the engi- neering writer by stressing the writer's duty to develop awareness of purpose and audience. Many of these contributors stated or implied that such awareness must govern matters Of organization and style, even if they described the development of this awareness in the context of simpler writing tasks than those of large-scale software projects. In general, from the perspective of software writers who must define purposes and audiences in a very complex context, contributors developed an accurate vision of the processes and products of engi- neering writing. Contributors discussed less diverse audiences and purposes than those described in the introduction to this study, and less complex texts than those described in chapter 1. Some continued to hold limited concepts of engineering writing, its audiences, and its authors. Yet a significant number of contributors recognized the writer's need to develop senses of purpose and audience in the context of a diverse audience and complex task. 81 CONTRIBUTORS' CONCEPT OF THE PURPOSES AND AUDIENCES OF ENGINEERING WRITING During the period 1981-85, IEEE contributors developed an expand- ing vision of how the factors of purpose and audience become involved in various kinds of engineering writing. Though many contributors assumed that each kind of writing implies simply-defined purposes and audiences apart from the context of actual audiences and their varied purposes, by 1983, others asserted or implied that the writer must finely tune the senses of purpose and audience to identify these variables, even if they offered limited guidance to the writer in contexts like large-scale software projects. In 1981-84, a relatively small group of contributors assumed that each kind of engineering writing, by its nature, implies simple de- finitions of purpose and audience, apart from the context Of specific purposes and audiences. Alex Andrews declared that writing specifica- tions clearly involves a ”legal rather than an instructional or in- formative" purpose, that the writer of a specifiCation need only appreciate the legal function of the text to understand its purpose (142). Herman Skolnik described the implicit Objectives of report-writing: "To research for facts and knowledge that answer important questions, evaluate the results critically, and organize the results into meaningful reports." Skolnik also defined the report-writer's straightforward responsibility to audience: "To report 6 the results so others may possess them fully" (72). Jean MacGregor 82 summarized the implicit purposes of the "arithmetic line graph" and "column graph"--to portray "movement of data over a long period" or "size or magnitude of elements over time" (102-03). James George and Anders Vinberg catalogued tables and "graphics," i.e., figures (95), and Kathryn Szoka classified four types of charts (98-100), by similar easily-recognized purposes. Robert Hays assumed that the writer may rapidly produce new proposals or manuals from master templates, and William Arnold, that the writer may employ varieties of "indentation, heading, graph, table, or paragraph," without adapting these texts to specific purposes and audiences (222). In 1983-85, a relatively large group of contributors recognized that various kinds of engineering writing require the writer to tune the senses of purpose and audience. Jeffrey Seisler suggested that the writer establish the purpose of a proposal in relation to the specific problem at hand and clearly state that purpose in the initial "ap- proach" section (58). T. M. Georges advised the writer to establish a clear sense of purpose and audience--a specific intent to make the "customer's life easier"--and shape the proposal around this intent (84). Beck praised Tim Whalen for stressing the proposal-writer’s consciousness of a specific audience. Beck encouraged the proposal writer to address primary questions this anticipated audience will pose: Does the writer express a clear sense Of purpose, "a proposed line Of investigation" and "a method Of approach to the problem" (56)? Joel Haness advised the editor Of any document to look for a clear statement of purpose and audience--"technician, engineer, managfir, [or] 83 executive officer"--to judge whether its author knows and addresses its specific purpose and audience (15). Exemplifying the best of this emphasis on knowing the purposes and audiences of particular kinds of writing, Gary Lynch advised the writer that the "purposes of instrumentation documentation" exist in relation to various categories of users, including the "designer-author," who might use the document as a device to recall the details of design in the future; the "successor" to the author-designer, who might need details beyond those the designer required; the "manufacturing engi- neer," who wants "to know the sequence of decisions that led to the selections of components"; and the "electronics technician," who needs details necessary to assemble or repair hardware. The author-designer may give his own purpose for the document first priority, but must "organize the report so that other users can find their information without much searching" (178-79). By 1984, the need for the writer to sense the diverse purposes and audiences of particular kinds of engineering writing became a prevalent theme. Frank Jamerson explained how the writer may recognize the audiences Of technical reports and shape their layout to suit these readers’ specific purposes. For instance, the writer of a company report, conscious of an internal audience, should introduce the subject with an "informative" abstract, then present the general purpose of the research, its conclusions, and the specific rationale for research in terms of the company's interests before detailing the methods and 84 results of research. Above all, the writer should seek to communicate the immediate practical consequences of research to busy "laboratory" and "divisional managers." In contrast, the writer of the journal paper, conscious of an external audience, should open with a "descrip- tive" abstract, then present a "scientific" rationale for research before the details of method, research, and conclusions. This writer should seek to communicate theoretical as well as practical impli- cations Of research to the "scientific community" (36). Similarly, James Mann and John Ketchum explained how the writer may reshape "technical materials for a variety of audiences and applications," supplement boilerplate by adapting a given technical content to various forms, "including reports, brochures, conference papers, magazine arti- cles, and seminars," that suit varied audiences (85). And Gail Ulrich described how writers of technical reports can successfully address such audiences--by becoming conscious of readers' levels of experience with technical subject matter. In 1985, contributors again stressed the importance of knowing purpose and audience to authors of particular genres Of writing. Joann Hackos explained that authors must anticipate the inertia of an internal audience before writing standards and procedures-—know how these readers may resist new procedures that would change their routine behavior. In two separate articles, Robert Greenly and Tim Whalen both stressed that the proposal writer who knows the audience by under- standing the customer's Request for Proposal can effectively organize 85 the proposal around the RFP. Alice Moorehead suggested that, before writing, the author of a technical report meet with a manager who will emphasize "purpose and audience concerns before organization and editing concerns," to place the writing activity in its proper per- spective (13). James Souther explained that the writer must understand the managers who will read the report to make the motivating goal of a report apparent--show that the report has an "implication to the company" and suggest specific future actions that appeal to these managers (5). And Dietrich Rathjens argued that "clarity" does not stem from the writer's ability to manipulate words and sentences alone, but develops as a "function of the target audience"--of the writer’s ability to apply the message to the reader’s particular background and level of expertise (42-43). Despite contributors' growing awareness that particular pieces of engineering writing exist in relation to specific purposes and audi- ences, contributors generally stopped short of describing writing like that of large-scale software projects, particularly, writing that de- velops in the context Of multiple audiences with diverse purposes. In nearly every case, these contributors assumed that a particular piece of writing addresses a single audience. Though many contributors re- cognized that purpose and audience are not intuitively Obvious, they often implied that the writer may follow a sense of purpose and audience established at the outset of the writing task throughout its remainder. In general, these contributors did not allow for a case 86 like the software writer's, in which the author must consistently es- tablish and re-establish multiple purposes and audiences throughout the course of the writing task. One contributor to the 1985 Transactions did provide the writer a means to evaluate and re-evaluate purpose and audience throughout a complex writing task. Mary St. John showed how the writer may identify "purpose" and "audience" with "The Teradata Document Template," 3 tool recording profiles of these two variables and eight others--"title," "timing," "approach," form," "writer," "input," "content," and "sche- dule"--on a single page (30). St. John explained how the writer easily changes this record on magnetic media while formulating and reformulat- ing definitions of purpose and audience throughout the planning stages. In this way, the writer continually re-evaluates these two variables. With St. John's tool properly applied, the writer's determination of purpose and audience then becomes a flexible process that extends throughout the prewriting, writing, and revision stages, not a single decision to simply define purpose or audience immediately before writing or in the course of drafting the first paragraph. St. John's tool Offers "inherent flexibility for...various types of customer documents," an easily revised format potentially valuable to writers in large-scale software projects. Although St. John did not specifically apply the tool to the situation of a writer who faces complex, multiple audiences with diverse purposes, her tool allows for the continual redefinition of purpose and audience such a writer may require. 87 This chapter has cited several articles from each volume of the IEEE Transactions 9h Professional Communication, 1981-85, to illustrate how contributors developed expanded concepts of the purposes and audi- ences of varied kinds of engineering writing. Between 1981 and 1985, though some contributors assumed that each kind Of writing has intui- tively-Obvious purposes and audiences, many recognized that the purposes and audiences of various kinds of writing exist in relation to their specific contexts, including the varied purposes of their audi- ences. Nevertheless, with one exception, contributors stopped short of explaining how the writer may understand complex purposes and audiences of engineering writing in contexts like those of large-scale software projects. CONTRIBUTORS' CONCEPT OF THE WRITER'S AUDIENCE Between 1981 and 1985, though many contributors assumed that the writer addresses a single kind of reader--one with limited reading aptitude or technical background--others made considerable progress toward defining an audience of readers in several categories, each category requiring its distinctive level of reading difficulty and technical detail, even if they still described an audience generally less complex than that of large-scale software projects. In 1981-82, many contributors assumed a single kind of audience limited in reading abilities or technical knowledge. Several 88 contributors prescribed the informal use of readability formulas to help writers fit text to an audience with limited reading aptitude. Kenneth Powell advocated applying the formulas to an audience with a lower than college reading level. Jeanne Barry prescribed "Computerized Readability Levels" to help engineers "keep the overall reading level 9th grade or below"--to lessen sentence complexity, simplify vocabulary, or reduce the number or syllables per word (46). J. Peter Kincaid, James Aagard, John O'Hara, and Larry Cottrell des- cribed a "Computer Readability Editing System" to help writers cope with a national "decline in reading ability"--to eliminate "un- II common...words and long sentences, replace ”difficult words and phrases" with simpler equivalents, and monitor "readability grade level" (38). Several contributors discussed how the writer may employ graphics to serve the limited reader. Arlan Saunders recommended "simple, interesting, and complete" illustrations to assist the reader who carries out assembly procedures (21). Richard Hodgkinson and John Hughes explained how the writer may use drawings rather than text to simplify procedural descriptions--partially because "important items can be emphasized" by showing "only the details necessary to convey the message in each drawing" (78). Richard Filley showed how "Chernoff faces"--circular faces "whose features, such as length of nose and curvature of mouth," represent statistical entities--help the average person process text more quickly (93). 89 Other contributors advised writers to adapt prose to those with limited reading abilities. B. C. Sharma explained how the author can apply readability formulas to the needs of such an audience, and M. C. Bailey and W. Pferd, how the writer may develop training materials for employees with limited reading abilities: by presenting "an equal amount of information in sizeable chunks and fewer than nine new com- mands" in each lesson (69). Stephen Goldfarb also described how the writer can serve such readers: "Forget your pride of authorship and the extent of your vocabulary"--use a diction suitable to the user's level of experience, not your own (15). While some contributors helped the writer serve an audience with limited reading abilities, several others showed writers how to address an audience with limited technical background. Marshall Atlas showed that an author can fit a manual to an "inexperienced user" by observing "errors and hesitations" on a test run and revising the sections of the manual associated with these difficulties. The author can Observe this user's attempt "to work with a machine, using only its manual as a guide," to develop a realistic concept of the reader's limitations (28). James Pilditch asserted that amateurs in technical fields should write instruction manuals because they can best address the inexperi- enced user's level of knowledge. Albert Joseph exhorted the writer to provide an opening rationale for training materials to define the place of the described function in "the overall picture of the company's operation" for novices, who lack a rudimentary concept of the function 90 (169). And James Hartley warned the writer to use flowcharts selec- tively because their technically-inexperienced audience may not "know in advance how to use such devices” (20). These contributors demonstrated a concern for the technically-limited audience to supple- ment their colleagues' emphasis on an audience with limited reading skills. John Maynard advised the writer to serve the reader with limited technical background by emulating the viewpoint of later beginning users--becoming the first user of software. Elizabeth Berry exhorted the author to provide the basic background "the user does not have" (22), and Susan Dunkle and Purvis Jackson recommended analogy to bridge the gap between the user's present limited level of technical knowledge and new knowledge. From 1983 through 1985, though contributors placed less emphasis on an audience with limited reading abilities, their interest in an audience with limited technical knowledge continued. In 1983, Patricia Baggett introduced "Four Principles for Designing Instructions" tailored to the nontechnical audience. Principle 1--"a criterion for good terminology for unfamiliar objects, actions, and situations"-- particularly suits such an audience. Principle 2 (correct juxta- position of visual and spoken elements in a presentation) and principle 4 (the correct order for viewing and practicing the contents of an instructional film) more concern audiovisual than written communica- tion, but principle 3--"decomposition of instructional material into 91 conceptual units” (102)--fits the writer who composes for a reader lacking in technical knowledge. According to Baggett, such a writer must not assume the novice's holistic concept of an assembly process, but carefully subdivide the process into discrete steps, each suiting the learner's "natural conceptualization" (99). In 1984-85, six articles concerned the writer who addresses a reader abashed by technical content. David Bradford discussed the author's use of "humor, irony, graphics (cartooning), ...personifi- cation, pronoun choice (first and second person), [and] eloquence (analogy and metaphor)" to make materials "user-friendly" to the nonexpert (66). James Gleason explained how the writer can adopt an organization tested with actual users, a brief content, a pleasing appearance, and appropriate language to suit the preferences and needs of the novice. Peter Martin described the characteristics of a II "friendly system, characteristics that might also typify a "friendly" piece of system documentation: its overall structure is readily apparent; its style is "congenial," though not "chatty or too per- sonal"; its nomenclature and syntax are "consistent"; and its logic is straightforward (62). In two separate articles, Daniel Plung and Carol Huber both showed technical writers how traditional literary figures of speech can help to communicate technical content to audiences with limited technical background. Diane Weaver explained how the writer in an organization can provide simplified in-house manuals for the user with limited experience to supplement the manufacturers' manuals 92 designed "for system experts" (27). This writer can provide internal guides appropriate to inexperienced users, who become confused by the jargon suited to experts. During the period 1981-85, though the concept of a reader with limited reading ability or technical knowledge persisted, the concept of a diversified audience with varying reading abilities and levels of technical expertise was also present, and it strengthened over the course of the five years. In 1981, several contributors recognized the writer's need to address a collection of readers, each with a distinct level of experi- ence. Sandra Pakin assumed readers' various "experience level[s] with data processing" (75). Susan Grimm asserted, "The writer must be able to write for all these audiences [the various levels of users who will employ a single system and its documentation] either in one document or in different documents." These audiences include both "managers with advanced degrees” and "clerks who have recently finished high school," people with a range of ability to understand technical content (79). In 1981, several other contributors warned the writer that reada- bility formulas do not assess the application of material to a diversi- fied audience. Bertram Bruce, Andree Rubin, and Kathleen Starr argued that readability formulas cannot measure varying levels of knowledge in such an audience. Janice Redish explained that readability formulas do not measure "how relevant the content is for the audience" or whether writing "will achieve its purpose with its audience" (47-48). 93 Similarly, Lawrence Frase argued that the writer may misapply reada- bility measures because these formulas "ignore differences in readers' goals" (49). Daniel Plung explained how readability formulas "command writers to prepare all material, regardless of intended audience, as if it is to be read by people with extremely limited vocabulary and reading abilities," that these measures do not assess its level of interest to segments in this audience, a more important variable than word or sentence length to determine the difficulty Of a passage (53). William Diehl and Larry Mikulecky further illustrated the concept of diverse audiences: the technical writer needs three different approaches for three categories of readers. The author composes written material that "serves as a reference only" for the user "reading to dO"--consulting the text intermittently and piecemeal while completing a complex task, and then only to answer specific questions about the procedure. The writer composes material to be "read more completely" for the user "reading to learn"--consulting the text away from the specific task at hand to memorize both the order and nature of the steps involved. The author composes material that serves only as a guide for the user "reading to assess"--scanning the text tO evaluate its application to a given task, perhaps to pass on the material to other users who will consult or read it more thoroughly while reading to do or reading to learn (6). The writer may address these three audiences by incorporating specific organizational and stylistic traits. To address the user who reads to do, the author may develop a 94 step-by-step organizational pattern and incorporate an index. To facilitate reading-to-learn, the author may include questions for the reader, an advance organizer, or a structured overview at the outset of the text and headings and subheadings throughout it. To assist the user who is reading to assess, the author may use executive summaries at the outset and graphic highlights throughout. Of course, writers may address readers who fall into various combinations of the three categories and must adopt the appropriate combination Of organizational and stylistic devices. Although Diehl and Mikulecky never specifically applied their classification to large-scale software projects, their scheme may clarify the difference in purpose between the user and developer of a software system. The user reads for a general, nontechnical descrip- tion to be sure that the system does what it should--he is "reading to assess." The developer reads for precise, technical detail in order to implement the system--he is "reading to do." In June 1982, Richard Braby, J. Peter Kincaid, Paul Scott, and William McDaniel described how the writer addresses technical instruc- tions to an operator using the text in two ways--"to perform a task" or "to learn to perform the task from memory"--analogous to Diehl's and Mikulecky's "reading-to-do" and "reading-to-learn" (61). The author composes these two types of technical instructions by incorporating appropriate media, for instance, instructions for an oscilloscope in combinations Of media suited to two distinct audiences. The author 95 assists the operator who performs the task at the oscilloscope with a 21-page narrative and 20-page illustrated text of the procedure. The author serves the operator who studies the text away from the oscillo- scope with a 116-page learning aid including photos, printed direc- tions, practice exercises, and self-tests (62-63). Like Diehl and Mikulecky, Braby, Kincaid, Scott, and McDaniel developed a concept of users with diverse purposes. In March 1984, Lidia Lopinto described a model Of manual design for the writer who addresses readers with different intentions and levels of technical understanding. Through "modular design," the author divides the manual "into modules...that can be easily referred to by those with diverse purposes" (30). For a given machine environ— ment, the author treats each piece of equipment in a separate module, each opening with a "summary" or "brief statement of content" and "introduction" or "discussion of the process design concept." The author includes sections that serve groups with distinctive needs and levels of experience in addition to these sections of modules that address all potential users. For instance, "Routine Operation" describes "how the equipment is to be operated and controlled" for the initially inexperienced user who must learn to use the equipment on a daily basis. "Maintenance" describes the ”compilation Of procedures for disassembling equipment and replacing parts" for the technician who has a comparatively sophisticated level of expertise and needs detailed documentation (30). 96 Lopinto's model of manual design supposes a situation closely analogous to that of large-scale software projects, in which diverse readers must use a single text. Yet Lopinto's model presupposes a text segmented into modules for various users, where each module addresses users with a specific level of expertise. Large-scale software pro- jects place a more difficult task on writers, who sometimes must compose a single text undivided into modules for several categories of readers, for instance, the text of the Part I specification reviewed in chapter 1, that must serve both the external "user" and the internal "developers." In the context of a large-scale software project, some texts, particularly Part I specifications, become vehicles for communi- cation between several classes of users and developers who must arrive at a mutual understanding of requirements. These varied audiences read the same parts of a text explaining these requirements, not different modules within such a text, to assess whether they all agree to these requirements. In the period between 1981 and 1984, Diehl and Mikulecky; Braby, Kincaid, Scott, and McDaniel; and Lopinto all described the author- reader relationship with increasingly sophisticated concepts of the reader and progressively less emphasis on the reader limited in reading ability or technical expertise. In December 1985, six contributors further refined the concept of the reader by identifying the "dis- advantaged reader." In his introduction to the December issue, Andrew Malcolm identified the "two classes of readers" for engineering 97 writing--"other engineers and the general public"--and further subclasses of users within these two classes: non-native readers of English, deaf readers, and readers with learning disabilities (1). Five other contributors to the December issue treated engineers' means to write for these subclasses. Kathleen Crandall described "specific strategies to alleviate the [reading] difficulties" of non-native and deaf adults (3). Alinda Drury summarized means to select vocabulary, structure sentences, and organize text so as to provide sufficient context clues for "non-fluent users of English” (11). David Crane and Andrew Malcolm discussed the composing processes and technological means by which the writer may create TV captions for hearing-impaired readers. Gerard Walter described the effects of diction on hearing-impaired students, and Larry LoMaglio and Victoria Robinson discussed the influence of passive constructions on the deaf. These contributors further demonstrated that the writer needs a concept of multiple users, one allowing for many more possibilities than the single user with limited reading abilities or technical background, by describing several examples of readers with special needs. Between 1981 and 1985, then, though some contributors continued to affirm the concept Of a limited reader who needs a simplified text, others envisioned a diverse readership that includes users with many needs. Contributors continued to refine the concept of a diverse readership, even if they did not describe the complex case of the 98 single software text that serves diverse audiences throughout its contents. CONTRIBUTORS' CONCEPT OF THE WRITER'S TASK As contributors to the IEEE Transactions eh Professional Communi- cation expanded their concepts of the writer's audience, they developed related concepts Of the writer's task. Throughout the period, many contributors emphasized relatively simple concerns of mechanics, organization, and style, but others recognized that mechanical, organizational, and stylistic aspects of writing must serve the writer's attention to purpose and audience. In this, these contribu- tors agreed with the Kinneavyan model of discourse, that subordinates organization and style to the larger purpose of the discourse, though contributors generally developed this perspective in relation to simpler writing tasks than those of large-scale software projects. Throughout 1981-83, in two ways, many contributors emphasized attention to basic matters of mechanics, organization, and style. First, these contributors motivated the engineering writer to exercise such attention to these basic matters of writing. Peter Schiff illustrated the need for motivation by reporting that 367 engi- neering graduates had rated speaking tasks as more important than writing tasks. Other contributors encouraged the engineering writer to take an interest in correct writing. Staff from the Royal Bank of 99 Canada argued that "Bad writing is bad manners and bad business" (63). Kenneth Powell commended the goal of Edmond Weiss's text for scientists and engineers: "To convince the reader that writing is a fundamental part of engineering and scientific work" (51). Rating the amount of time engineers spend writing, reading, or orally delivering reports at about 50 percent, Carol Barnum motivated the engineer to take a proper interest in verbal communication, and, attempting to evoke high aspira- tions, Arn Tibbetts advised the engineer to emulate "great writing" (11). Second, contributors provided instruction in basic mechanics, organization, and style. Several offered tutorials in spelling and usage. Sarah Montoya treated the distinctions between single and double consonants and "who" and "whom"; Richard Nailen explained differences between words Of similar spelling (e.g., "eminent" and "imminent") and meaning (e.g., "imply" and "infer") (117); and Robert Schoenfeld argued against using nouns as verbs. Besides providing tutorials in mechanics, these contributors treated basic stylistic and organizational considerations. Thomas Montalbo advised writers to "Say It in Threes"--"three points, three qualities, three reasons"--to organize the process Of writing a speech (128). C. C. Crawford explained a basic organizational technique, the "Crawford Slip Method," the recording of important points on "uniform slips of paper" and the "sorting and classifying" of these slips into an "output report" (187). Numerous contributors advised writers to accomplish a simple, clear 100 style by reforming their diction. For instance, Richard Nailen, Ethel Romm, Nick Tredennick and Brion Shimamoto, Jim Corey, Judith Bronson, and Carla Echols and Lois Pryor all discouraged writers from using the passive voice. These contributors assumed writers' ignorance of a stylistic principle long held and disseminated by teachers of writing-- preference for the active voice--and sought to inculcate this principle in engineering writers. Richard Nailen, Ethel Romm, Nick Tredennick and Brion Shimamoto, Jim Corey, Judith Bronson, and Kathleen Booher and Wilma Davidson all encouraged these writers to simplify their diction, to eliminate excess words and overredundancy. These contributors assumed engineering writers' propensity to verbosity and need to learn the basic techniques for simplifying style. In 1984-85, some contributors still emphasized attention to basic matters of mechanics, organization, and style like their predecessors in 1981-83. First, some still motivated the engineering writer to recognize the importance of mechanical correctness and basic organizational and stylistic techniques. M. C. Cosgrave listed "poor motivation to communicate" as a chief cause of engineers' "uncommunicative writing habits" (38). Thomas Burke instructed engineers that "You'll Never Get Ahead in Engineering If You Can't Make Yourself Understood." Susan Feinberg and Jerry Goldman suggested fear of writing as a major cause Of poor engineering communication by describing the measurement of "writing apprehension" among engineering students from Illinois 101 Institute of Technology and Arizona State, and, presumably, among engineering graduates (155). Gary Bates explained why engineers write poorly: the "quantity of communication matters more than the quality"; it has "not been 'in vogue' for engineers to be good in English"; engi- neers are "too dependent on someone else to correct our writing"; and "we have decided that there are new rules for writing and new words to coin" (89). Laura Casari argued that industry recognizes the need for engineers to have formal training in technical communication, but that universities often underestimate the need by requiring engineers to take few credit hours in this field. Second, several contributors still helped engineering writers develop basic knowledge of organization and style. Joan Knapp ex- plained how to organize a report into introduction, body, and con- clusion in ten orderly steps. William Ledbetter reviewed The Crawford Slip Method--a detailed description of C. C. Crawford's approach to organizing content. And William Fleischauer explained a method for organizing procedural descriptions that arranges information in an "easy-to-read" format (31). Roger Muenier reviewed Style and Reada- bility th Technical Writing, by James DeGeorge, Gary Olson, and Richard Ray, 3 text incorporating "expressions that are part of the techni- cian's working vocabulary"--for example, "'slots' (for subjects, verbs, and Objects), 'left-branch' and 'right-branch additions' (for phrases and clauses)"--to circumvent engineers' ignorance of traditional stylistic terminology (233). James Hartley explained how text-editing 102 software helps writers revise by highlighting instances of potentially weak mechanics, usage, and style: spelling, punctuation, overredundan- cy, split infinitives, passive verbs, abstract words, sexist phrases, and awkward expressions. Michael Kantrowitz recognized as "editorial priorities" relatively low-level organizational and stylistic tasks, for instance, an "integrity check" of references to tables and figures, "deleting unnecessary words, phrases," " correcting mechanical errors," "revising format," and "reorganizing" (13). Similarly, Charles Beck identified "rewording" as the ultimate step of the editing process-- this to remedy inappropriate verbs, poor sentence openings, and misused coordinate and subordinate conjunctions (43-44). In 1981-83, while many contributors stressed the importance of mechanical correctness and effective stylistic and organizational strategies, others suggested that the writer should subordinate these concerns to matters Of purpose and audience. Exemplifying this trend, R. John Brockmann praised J. VanDuyn's handbook for the data processing professional because it demonstrated the writer's need to understand these factors: to develop a "sense of the complexities of purpose and audience that confront documentation" (45). In 1981-83, contributors discussed four ways the writer may subordinate organizational and stylistic concerns to matters of purpose and audience. First, some contributors particularly encouraged writers to develop the lesser traits of their texts around technical purposes and 103 audiences. Patricia Wright advised writers to organize their work around the applied technical purpose of the procedures they describe: "how readers will use the document" (10). Ruth Power suggested that the writer develop the text around the purposes of a technical reader- ship from the outset of a project: "work as part of the front-end engineering" (139). Second, other contributors encouraged writers to determine large stylistic traits--the media of the discourse--on the basis of the purposes they serve within the discourse, for instance, their psycho- logical effects On an audience. Robert Frye advised technical communi- cators to use cartoons, interpretive sketches, and WHIF charts ("when and if" charts portraying sequences of events) to "contribute, rein- force, Or illustrate the verbal component" (87). R. J. Joenk advocated the pictorial as opposed to the verbal mode of representation because an audience can remember "designs, illustrations, pictures, and faces ' or process graphic images "in parallel," but must use an as images,’ "intermediate coding step" to remember words, or decode text "serially" (58). Robert Waller, Paul LeFrere, and Michael Macdonald-Ross suggest- ed using a second color to highlight text because it helps the reader detect "salient features," organizes the reader's "visual field," and "generates [appropriate] expectations" in the reader (84). Stephen Marcus advocated type styles that raise the reader's level of com- prehension, and James Gleason favored using an illustration at the beginning of an article to engage and hold the reader's attention. 104 Third, in contrast to contributors who stressed organizational strategies the author may apply to surface traits of the text, several advised the writer that the effect of a text on its audience depends on the author's organized approach to the reader. Kenneth Powell advised the science writer to carefully and purposefully approach the reader: systematically attempt "to reduce the emotional involvement of the reader's response rather than evoke it" (189). Ashis Gupta described the method of "profiling," through which the writer defines the relationships between the "source" (the corporation the writer repre- sents) and "receiver" (the corporation the writer addresses) before writing. With this method, the writer describes the sending and re- ceiving parties' "image" and "bias" (basic attitudes and values) in a short preliminary "profile" so that he may later compose with a well-defined concept of the source-receiver relationship (199). Susan Dressel showed the author of a technical report how to develop an approach to the ultimate audience outside the company: address a first audience, the inside editorial staff, in a practice run. Contributors from the Document Design Center of the American Institutes for Research developed the "Process Model of Design" to help the writer organize an approach to the audience. Through "Pre-Design Steps" of this model, the author systematically defines the "purpose" and "audience" of the document before beginning the "Design Steps," in which the author, having systematically defined the audience, may then "organize for [the document's] audience" (177). 105 Fourth, several contributors asserted that the writer in a corporate context must take on a wide organizational role, not only in relation to individual texts, but also in relation to various authors. William Houze maintained that technical writers of the future will "perform as information managers, not as wordsmiths only," to bring coherence to the document process (38). These writers will work with management to develop "perspective on the internal logic of a docu- ment's organization and content" and analyze "the document's basic purpose and its stated and implied meaning or basic message to the reader-user" (41). These writers will then coordinate the parties to a text--including technical authors, peer reviewers, and client repre- sentatives--to serve its purpose and orientation to the audience. John Mashburn and Janice Vantrease described the writer who acts as an intermediary editor to define the purposes and audiences of varied texts by different authors. Each text may have multiple purposes and audiences within the overall framework Of company organization. For instance, a product specification may serve a systems analyst who is attempting to discover whether that product is in its final form before he writes a user's manual to explain it. On the other hand, the same specification may serve a manager "trying to set up an appropriate training program for the wiring technicians" who will work with the product the specification describes (166). The company thus needs an intermediary between authors and these audiences with varied purposes, 106 a writer/editor who can identify and describe for authors the purposes and audiences of documents. Contributors in 1984-85 discussed the same four ways writers may develop and promote senses of purpose and audience as their counter- parts in 1981-83. First, some contributors again encouraged the writer to develop the lesser traits of their texts around orientation to technical purpose and audience. Herbert Michaelson argued that the engineering writer should organize the text around the needs of two audiences, both "technical staff and executives...make the appropriate choice for best impact on the audience and, at the same time, for fulfillment of the author's own objectives" (153-54). Karl Gwiasda suggested that minor stylistic problems, for instance, overuse of the passive voice, Often disappear when the engineering writer composes with full awareness of a technical purpose and audience. Second, some contributors again encouraged the writer to determine large stylistic traits--the media of the discourse--on the basis of their ability to serve the purpose of the discourse. Paul Anderson advised the writer to consider other media besides print to accomplish these purposes; in contrast, Frank Smith exhorted writers to fully appreciate the potential of the print medium itself--a "plastic art" rather than "linear...process"--that may serve their purposes as well as other, apparently more sophisticated media (102). 107 Third, other contributors again stressed that the effect of a text on the reader depends on the writer's organized approach to this audience more than the practice of basic organizational strategies for composition. Several emphasized the writer's application of logical and critical thinking skills to the writer-reader relationship: ”problem-solving strategies" (Joann Hackos 180) and skills as "problem- solvers, organizers, communicators, and educators" (Gina Burchard 26). Fourth, a few other contributors again asserted that the technical writer of the present and near future should assume a wider organi- zational role than the author who orders and rearranges portions of a single text--this writer should coordinate other authors to help them achieve consistent senses of purpose and audience, and in this way make these senses evident in the text. Charles Beck suggested that the writer should help each author insure that "the text actually meets its intended objective" (43); Roger Masse, that the writer should help each author modulate ”content" and "tone" to make the text appropriate for its given purpose and audience (35); and Herb Smith, that the technical writer should organize authors to target "audience needs and interests" (47). James Souther described the writer who profiles for authors the reading habits Of upper management so that these authors develop appropriate writing strategies to target this audience, for instance, emphasis on the introduction, abstract, and conclusion of a technical report, the portions upper management will most likely read. Gary Abshire and Dan Culberson described how such a writer organizes and 108 ' where coordinates "a successful team approach to good documentation,’ all authors work toward the same ”objectives"--”the purpose and scope of each document"--established as functions of internal and external audiences (39). If the IEEE contributors stopped short of suggesting a coherent approach to writing tasks as complex as those found in large-scale software projects, in which a lead writer must coordinate the work of multiple authors in relationship to diverse audiences, they still did much to clarify the complex nature of the engineering writer's task. Though many contributors addressed the writer whose main task involves attention to basic mechanics, organization, and style, others addressed technical communicators who faced a further task: to establish the purposes and audiences of writing and shape the traits of discourse around these purposes and audiences. SUMMARY Contributors to the IEEE Transactions eh Professional Communi- cation, 1981-85, have made progress toward describing complexities of purpose and audience in contexts like Lear Siegler, Inc./Instrument Division. First, while some contributors have developed limited con- cepts of the engineering writer's senses of purpose and audience by assuming that these senses develop simply, others have shown that the writer must cultivate these qualities, and one has explained how the 109 writer may do so in a flexible manner. Second, though some contribu- tors have held a relatively simple concept of the engineering writer's audience by assuming that the writer's audience includes readers with limited verbal or technical abilities, many have described a diverse audience including readers with several levels of verbal and technical ability. Third, contributors have developed an expanding concept of the engineering writer’s task. Though some contributors have described the writer's major task as basic mechanical, stylistic, and organi- zational considerations, many have described this task as awareness of diverse purposes and audiences. In these ways, contributors have made progress toward defining the writer's senses of purpose and audience in settings like large-scale software projects, where the large number of writers and audiences involved in written communication complicate the writer's task. CHAPTER 3 This study will now focus on writing in one large corporation, Lear Siegler, Inc./Instrument Division, a producer of software for the aerospace industry. Through a survey of managers and coordinators of writers, this chapter will investigate to what degree software writers in this context have awareness of purpose and audience, particularly, the latter. In this survey, managers and coordinators will, to a limited extent, assert writers' need to better develop a sense Of purpose. Managers and coordinators will also report writers' weak awareness of audience, though they will often dismiss this weak awareness as unimportant. INTERVIEWS WITH MANAGERS AND COORDINATORS 0F WRITERS The managers and coordinators surveyed (see Table 1) represent two kinds of involvement in software writing. The managers of writers, including the Vice President of Engineering, division managers, and section managers, often participate little in the day-to-day processes of writing, yet they develop awareness of how the written products serve users outside the company through direct contact with the customer. The coordinators of writing, including several "technical writers," do little writing themselves but Often develop at least second-hand knowledge of outside readers. These coordinators gain this 110 111 Table 1. Managers' and Coordinators' Positions and Affiliations with Projects RESPONDENT POSITION AFFILIATION 1 Division manager Commercial 2 Section manager Commercial 3 Department manager Commercial and military 4 Division manager Commercial and military 5 Department manager Military 6 Vice president Commercial and military 7 Department manager Commercial and military 8 Section manager Military 9 Department manager Military 10 Technical writer/ document coordinator Commercial 11 Advanced flight management researcher Military 12 Technical writer/ document coordinator Military 13 Section manager Commercial and military 14 Section manager Commercial and military 15 Section manager Commercial 112 knowledge from contact with managers and lead writers and, in part, share this knowledge with writers. The advanced flight management researcher occupies a unique slot--his activities include management and coordination Of other writers as well as considerable writing. Throughout the survey, managers and coordinators describe two further kinds of involvement in software writing. First, according to these respondents, lead writers, or "lead project engineers," do limited writing, but they work with managers and coordinators to organize the processes of software writing. Through contact with managers, coordinators, and the customer, lead writers develop con- siderable knowledge of the outside audience. Second, the writers themselves have the least awareness of the external reader. Their knowledge of audience is usually second-hand, gleaned from contact with managers, coordinators, and lead writers. The survey will also show how the kinds of writing participants produce, whether proposals, engineering documentation, or user docu- mentation, influence their awareness of audience. In Kinneavyan terms, writers of user documentation have an informative aim: they must anti- cipate how the customer will use the text to Operate or maintain a product. On the other hand, writers of engineering documentation have a scientific aim that demands less consciousness of how their audience will use the text. These writers' first concern is an accurate description Of the product itself. The survey results will illustrate how participants' affiliations with projects influence their awareness Of audience. Those managers 113 and coordinators affiliated with commercial projects generally indicate that the writers with whom they work possess a greater awareness of audience than those assigned to military projects (see Table 1). Writers of engineering documentation for commercial projects, that is, projects for nonmilitary customers like the Boeing Corporation, are more likely to communicate with the outside user than their counter- parts in military projects, that is, projects for the US Army, Navy, or Air Force. This higher level of contact generally fosters greater awareness of audience among writers of documentation for commercial projects. The survey of managers and coordinators of writers will illustrate how participants' levels of involvement in software writing, the writing tasks they do, and their project affiliations interact to make them aware of audience in different ways and to varying extents. The survey results will also show how managers and coordinators evaluate writers' senses of audience and purpose. Managers and coordinators believe writers have limited awareness of audience and sense of purpose. Managers and coordinators place little value on writers' sense of audience, though some believe writers need a more compre- hensive understanding of the purposes texts serve within software projects. During fall and winter 1984-85, I administered a survey including the six questions that constitute the subheadings of this chapter to 15 managers and coordinators of writers and lead writers at Lear Siegler, Inc./Instrument Division. In advance of each interview, the Manager of 114 Human Resources signed and mailed to each respondent a letter intro- ducing the purpose of my research. The letter mentioned no specific goals, only that I would be "interviewing LSI/ID personnel involved in the process of writing documentation." Later, when I called each in- dividual to arrange an interview and arrived for the session, I avoided specific reference to these goals. After using a tape recorder to interview the first respondent, I concluded that it might discourage candid response. I read six questions to the remaining 14 managers and coordinators of writers and recorded their responses on paper. Respondents could thus answer my questions with few preconceptions about my goals or apprehensions about speaking frankly. With guidance from my section manager, I compiled a list of 15 managers and coordinators of writers from throughout the Instrument Division. This manager had the familiarity with company personnel I lacked, and he offered many suggestions. Together, we selected a sample that would represent wide perspectives on software writing. The six survey questions assess how managers and coordinators perceive writers' and lead writers' activities in software projects. Question 1 establishes the kinds Of writing done; question 2, writers' strengths and weaknesses; and questions 3 through 6, the relationships between writers and their audiences. The following sections report managers' and coordinators' response to the six survey questions. Each section summarizes the general re- sponse to one question, paraphrases all respondents' answers in tabular 115 form, and explains how these answers elucidate the purposes or audi- ences of software writing at Lear Siegler, Inc./Instrument Division. QUESTION 1: "Please describe the kinds of documentation which the customer or sponsor requires for each project." The response to question 1 identifies the kinds of writing that participants do (see Table 2). These writing tasks include the four main groupings surveyed in chapter 1: a. Proposals. Other writing tasks may not begin until the company submits proposals to the customer and the customer's acceptance results in a contract. Because the number of proposal writers is small, only respondents 9 and 11 mention proposals. b. Specifications. Most respondents mention specifications-~Part I's, requirements specifications, that provide an overview of a system; and Part II's, design specifications, that lay out the detailed structure of programs so that programmers can write code. Specifica- tions are not only the most-mentioned but also the most voluminous form of documentation: a Part II or design specification may fill as many as 30 volumes, or 12,000 pages (res. 10). In conjunction with specifica- tions, writers prepare preliminary and critical design reviews, where they present to the customer summaries of Part I and Part II contents through slide presentations. c. Test documents. Seven respondents list a common form of writing that follows the writing of proposals and specifications in the 116 sequence of a project: the test document--the Test Plan, Test Pro- cedure, or Test Report--that describes how programs will be or were tested. d. User documentation. In the final phase of documentation, writers compose guides and manuals for Operators, programmers, and maintenance personnel who will use and maintain software. Five re- spondents mention various forms of user documentation. In addition to texts in the four main groupings above, respondents mention progress reports, technical papers, and technical reports, documents that serve informative purposes for internal and external readers. Progress reports help internal managers or the customer assess the progress of specific projects. Technical papers and technical reports keep internal engineers and the customer abreast of important research with significance for current or future software projects. 117 Table 2. Question 1: "Please describe the kinds of documentation which the customer or sponsor requires for each project." EEEEON' CUSTOMER-REQUIRED DOCUMENTATION 1 Requirements specifications (Part I's--written by systems analysts). Design specifications (Part II's--for software and hard- ware). Test documents (for modules or circuit boards at the lower level, functional/system/test reports at the higher level). Many figures and tables which the technical writer must master, especially for Structured Analysis/Structured De- sign. 2 Part 1's (not detailed--written to cover combinations which could occur at time written). Part II's (specific implementation). Design implementation documents. 3 N/A 4 Specifications, test reports, requirements documents. 5 Final reports done according to military standards. Operational manuals (procedures for using equipment). 6 N/A 7 Technical manuals: operator’s manuals, maintenance records, and parts catalogs. 8 Part I's, Part II's. Computer users' manuals. Test plans, procedures, and reports. 9 Initial documentation: Proposals (narrative text describing problem, proposed solution) and Software Development Plans (responses to customer's specific questions regarding proposals). Specifications: Part I's (first documents of design) and Part II's (detailed design). Test documents: Test Plans, Test Procedures (more detailed than plans), and Test Reports (results of tests). N/A = Not applicable--respondent works with too many customers and projects to list all of the kinds of documentation. 118 Table 2 (cont'd.) EESPON CUSTOMER-REQUIRED DOCUMENTATION 9 Others: progress reports, preliminary design reviews (cont'd.) (slide presentations which exist in document form as well as on slides), critical design reviews (more detailed than preliminary design reviews--presented to customer at LSI/ID). Technical papers which engineers write for presentation at conferences. 10 Software Design Specification (SDS) (purpose: shows how software is to be designed, difficulty: any programmer with 2 years of college experience can understand and write code from; volume: 30 volumes). 11 Proposals: Short-term (in that they do not usually stay around for years--once accepted or rejected, they are thrown away or shelved). Present possible solution to a problem, but do so by underexplaining, without hanging possible negatives on. NO feedback, except on a few minor details. Specifications: 0verexplain--include all of the details except for design/maintenance. Plenty of feedback if information presented is in- sufficient. Technical Reports: Long-term (results of study reports which will be around for as long as five years). Government and aircraft manufacturers will look at these reports and get impressions of writer's work. 12 Part I's (Computer Design Documents). Part II's (Computer Program Product Specifications). Test documents: plans, procedures, and reports. Users' manuals (for programmers). 13 Specifications (Part 1's and Part 11's). 14 Quality Test Reports. Electronic Interference Test Plans. Acceptance Requirements Documents. 119 Table 2 (cont’d.) §§§$ON- CUSTOMER-REQUIRED DOCUMENTATION 15 System Requirements Specification (Part I). System Design Specification (Part II). Pilot's guides, test specifications, and reports. 120 QUESTION 2: “What are the strengths of writers involved in the documentation process at LSI/ID? The weaknesses?" In their answers to question 2, respondents generally emphasize writers' weaknesses, including their inability to compose correct, clear writing, but particularly their lack of an overview or sense of purpose (see Table 3). Respondents l, 2, 3, 4, 6, 8, 9, 11, and 12 all describe writers' strengths as technical experts and weaknesses as writers. Only respondent 10 voices the opposite opinion: that writers are competent to produce correct, clear writing but lack technical background. Of those respondents who identify writers' weaknesses, some men- tion erroneous grammar, poor spelling, or limited vocabulary (res. 8 and 9), but a few more describe shortcomings on a larger scale, all of which, in some way, involve a weak sense of purpose, and one of which directly implies a weak sense of audience. Respondent 5 mentions writers' inability to "stick to the point," to subordinate minor technical details to the main point the writer is trying to make, in other words, to keep the overall purpose of the writing in control of the details. Respondent 2 identifies writers' weak sense of both pur- pose and audience in their failure to communicate clearly and accu- rately to "the nonprogrammer," to target their writing to the purposes of a less technical audience than themselves, an audience that does not want to know minor details of programming, but to develop an over- view of a computer system. By stating that the new structured methods I force writers to be "rigorous and complete,’ respondent 15 implies 121 that writers are not so presently, in other words, that they do not address the main technical purpose of writing without introducing irrelevant details, yet still comprehensively cover the necessary territory. Respondent 14 identifies writers' weak sense of the need for documentation and their resulting tardiness in submitting it. Respondent 13 specifically mentions writers' weak "sense of purpose," their lack of an "overview" and sense of the "program" (i.e., project) within which their writing serves its purpose. A few respondents describe writers' strong sense of purpose. Re- spondent 7 implies that most writers communicate a clear sense of pur- pose--they can "identify problems and recommendations for solutions”-- though he admits that "not all writers can do these things." Respond- ent 10 describes writers' "unity of purpose," perhaps because this respondent works in the commercial sphere, where, as the response to later questions will demonstrate, recognition Of the customer's needs and a motivating sense of purpose result from close contact with the customer. Generally, respondents emphasize writers' weaknesses rather than strengths, yet they demonstrate no clear consensus in identifying these weaknesses. Two mention relatively mechanical concerns, but the others seem unconcerned by matters of usage or spelling. Five in some way recognize writers' need to develop stronger senses of purpose, but two respondents hold that writers have adequate senses of purpose. From their collective responses, the need for a stronger sense of purpose arises as a significant concern, but by no means a point of consensus. 122 Table 3. Question 2: "What are the strengths of writers involved in the documentation process at LSI/ID? The weaknesses?" RESPON- DENT STRENGTHS AND WEAKNESSES 1 Writers have strong technical backgrounds, experience with varied document types, and familiarity with graphic tech- niques. However, they prefer engineering work to writing. 2 Writers cover the code thoroughly if not in an understanda- ble way. In requirements specs, they are too detailed as to implementation. In design specs, they are not descriptive enough: they don't do enough for the nonprogrammer. 3 Writers are not educated in writing skills. However, the two coordinators who are not engineers and the proofreaders help make up for their lack. 4 There are three types of writers: engineers, technical writers, and technical publications personnel. Engineers produce a good technical output, but rate between poor and good language-wise. Technical writers have good writing skills, but their writing is Often inaccurate because they have difficulty coping with day-to-day changes. Tech. Pubs. writers produce high quality writing partially because they write "when things are settled down.” 5 Several PhDs in the Advanced Development Organization have an analytical bent, unique talents for writing proposals. Almost everybody in ADO can write, but proposal-writing is a unique art. Writers in ADO have few weaknesses, but in the rest of the company, some writers don’t know how to stick to the point. 6 Writers at LSI/ID have good technical background and relatively long histories with the company (Often 15-20 years), but writers show weakness when they must write in areas they know little about. A writer must be involved in the product he's writing about. 7 Most writers have the ability to express themselves well, to identify problems and recommendations for solutions, but not all writers can do these things. 123 Table 3 (cont'd.) RESPON- DENT STRENGTHS AND WEAKNESSES 10 11 12 13 14 15 Writers at LSI/ID are very technical, often too technical. Some don't know how to write: they demonstrate bad grammar and a small vocabulary. Engineers all have thorough technical understanding, but the level of their communication skills varies widely. Some are good communicators, but others are weak in their organiza- tion of ideas, grammar, and spelling. Some are reluctant to write and consider writing overly time-consuming. Writers are able to develop cohesion of document, unity of purpose, and a meaningful package, but they do not have a strong enough technical background. Writers have thorough knowledge of subject matter and a good ability to communicate, to write so that others can under- stand, but they sometimes take the easy way out. When writers in an engineering environment do not read their own writing critically, it quickly deteriorates. Writers know their subject, but don't know how to talk about it. They feel little motivation to write well. Writers have a good command of oral and written English, but they have no overview or sense of purpose: their sense of each program is weak. Writers are capable, but they are tardy in completing documents. They put insufficient stress on documentation. Nevertheless, the recording of data here is less expensive than in many other companies (15% as Opposed to 50%). Because recording data is so expensive, the federal govern- ment spends 8 billion dollars per year on paperwork (actually much more: the figure is from 1971). Engineers generally are very bad writers--this has been a major problem in this industry. Recently, we've been getting away from using Standard English to force people to be rigorous and complete, to get away from ambiguity-~specifically, we've been using a brand of English called Structured English in combination with other structured techniques. 124 QUESTION 3: "Who are the writers and end users of this documentation (in terms Of positions and levels of expertise)?” In their response to question 3, managers and coordinators describe writers as experts in specific technical areas (see Table 4). Only respondent 4 qualifies writers' technical expertise. In general, managers and coordinators reinforce their response to question 2 by mentioning writers' technical ability and verbal inability. Some managers and coordinators cannot specifically identify the "end users." Respondent 2 is "not sure who uses [the] documentation at Boeing." Respondents 9, 13, and 14 describe the readers in broad cate- gories: "military personnel of varying levels of expertise," "technical people unaware of who the writers are and how they write," and "people who may or may not know what they want." Respondents 4, 6, 10, and 12 provide some guidance for interpret- ing their associates' lack of specificity. Respondent 4 suggests that customers may not use delivered documentation "at all," that "people [at LSI/ID] at varying levels use software documentation to monitor development and maintain software, or to become familiar with soft- ware." He identifies the users as people internal to LSI/ID, not the customer. Respondent 10 also mentions internal users--"software engineers and software verification people at LSI/ID"--as well as "the customer." Respondent 6 explains that the customer will indeed use pilots' guides and other manuals addressing "immediate practical need." 125 But respondent 12 limits the customer's use of specifications: procure- ment people generally assess only the format of documentation dictated by guidelines like Military Standard 490 (US Department Of Defense) (correct paragraph numbering, inclusion of required figures and tables, etc.) although they may study a Part I or requirements specification to get a general idea of the complete program. Of all respondents sur- veyed, only respondent 15 challenges limited customer use Of speci- fications: he describes the end users (of Part I's) as "technical experts at Boeing who like to see every detail of what LSI/ID is doing, who work with individuals on a one-to-one basis." The response to question 3 suggests that the term "end users" is misleading. This term implies an audience external to the company. In fact, several respondents explained, internal readers are Often as important as external ones. Writers and lead writers may often expect an external reader to scrutinize a Part I specification, but, in many cases, they may assume that Part II's will receive cursory treatment. Writers of Part I and Part II specifications must often anticipate how system designers and programmers inside the company will use the written product. 126 Table 4. Question 3: "Who are the writers and end users of this documentation (in terms of positions and levels of expertise)?" RESPON- DENT WRITERS AND END USERS 1 In Systems Department: fairly senior engineers with special- ized experience or those who learn new areas quickly (usually individuals with Master's degree). In software/hardware design: individuals with at least B.S.; some PhDs. 2 Writers: designers--software code people. Users: not sure who uses documentation at Boeing, but pro- ject staff looks at it. 3 N/A 4 Writers: Engineers--high technical level, lower verbal ability. Technical writers--lower technical level, higher verbal ability. Technical Publications writers--high technical and verbal ability. End users: LSI/ID--people at varying levels use software docu- mentation to monitor development and maintain software, or to become familiar with software. Customers--use for software maintenance (if they per- form this task) or not at all. 5 Writers: very senior, highly technical people, Often with PhDs. End users: government laboratories--strongly technical people. 6 Pilots' guides, user documentation: writers must address end user with immediate practical need. Proposals: writers must address end user who needs to be sold on a product. Software Requirements Specifications: writers must address user who needs good definition of system and software. N/A = Not applicable--respondent works with so many projects that he cannot list all of the writers and end users in a reasonable length of time. 127 Table 4 (cont'd.) RESPON- DENT WRITERS AND END USERS 10 11 12 Writers: people from the military with avionics maintenance experience. End users: commercial and military pilots, avionics mainte- nance personnel. Writers: usually college graduates with experience. End users: Air Force (8th grade education level?). Writers: engineers of varying levels of expertise. End users: military personnel of varying levels of exper- tise. Writers: software engineers. End users: software engineers and software verification people at LSI/ID, the customer, and, to a limited extent, management. Proposals (for study or production programs): Writers--senior people with strong technical back- ground. Readers--people without technical background. Reports: Writers-~junior and senior people with strong technical background. Readers--their counterparts. Specifications: Writers--all levels. Readers--their counterparts, or lower technical level. Writers: Electrical engineers (base level--first or second job out of college). Project engineers (supervisors of these base-level engineers). End users: Procurement people in the military or industry interested in proper format rather than content. Exception--procurement people interested in Part I's content to identify the design of the complete program and anticipate possible design problems. 128 Table 4 (cont'd.) RESPON- DENT WRITERS AND END USERS l3 Writers: project people (designers), Configuration Manage- ment specialists. End users: technical people unaware of who the writers are and how they write. 14 Writers: people who write to meet a contract. End users: people who may or may not know what they want. 15 Writers: people with at least a 3.8. in electrical engineer- ing, avionics, or a related field whose strength is not necessarily writing. End users: technical experts at Boeing who like to see every detail of what LSI/ID is doing, who work with individuals here on a one-to-one basis. 129 QUESTION 4: "To what extent are the writers aware of the end users' positions and levels Of expertise?“ Question 4 surveys writers' awareness of their audience, at least, as managers and coordinators measure this awareness (see Table 5). The ratings of this awareness range from low to high. Respondents 2, 8, 11, and 13 state that writers are not aware of the end users; re- spondents 1, 3, and 12, that writers are aware only if they are coordinators or lead writers (i.e., "lead engineers"); respondents 4, 9, 10, and 14, that writers are somewhat aware; and respondents 5, 6, 7, and 15, that writers are very aware. Respondents offer significant reasons for some writers' lack of awareness. TO explain the lack, respondent 1 mentions the division between readers inside and outside Lear Siegler, Inc./Instrument Division (LSI/ID): writers may not be "aware of users outside LSI/ID, but are aware Of users inside [the] company." Respondent 4 also mentions this division: "the people who actually use the system never see the documentation-~only the development people [at LSI/ID]." Respondents 8 and 9 agree: the only true user is inside LSI/ID; the customer "Often is not looking at the documentation"; and "readers of proposals will probably read only the first few pages of a document." On the other hand, to explain why at least some writers are aware of external readers, respondent 15 describes bona fide users from both outside and inside the company: "The end user may be a pilot, a main- tenance person, the airline, an engineer at Boeing [or another 130 customer], or an engineer at LSI/ID" who has real use for the document, and the writer who knows that he addresses such users may become very aware of their situations to "try to account for all Of their needs." Respondents indicate that writers' awareness of audience ranges from low to high. Managers' and coordinators' responses again suggest that the concept of the "end user" must expand to include all users-- external or internal to Lear Siegler, Inc./Instrument Division. The term "end user" signifies an external party many writers may not know, but the term "user" encompasses an internal user that most writers know. 131 Table 5. Question 4: "To what extent are the writers aware of the end users' positions and levels of expertise?" RESPON- DENT AWARENESS OF USERS 1 Writers are not that aware of users outside LSI/ID, but are aware of users inside company. Coordinators know the end users' needs. 2 They are not aware. 3 Writers are not aware. The lead engineer knows the customer, the level and needs of the reader. 4 Writers are 50% aware of the end users. The people who actually use the system never see the documentation--only the development people. The users may not be aware Of new documentation methods (e.g., Structured Analysis), so writers must educate the users. 5 Writers are very aware through longstanding relationships reinforced by telephone communication. 6 Writers are very aware. 7 Writers are very aware inasmuch as they have experience in the end users' fields. Exception: we have no former pilots writing, and are weak in writing documentation for pilots. 8 Writers are not aware at all: they assume too much knowledge on the end users' part, are not at all detailed, especially in computer and Operator users' manuals. They should be straight to the point, but detailed. There is little feedback from the customer, who Often is not looking at the documentation. 9 Writers assume readers similar to themselves. Actually, some of the readers of proposals will probably read only the first few pages of a document, but others will read for more detail--there will be several classes of readers. Writers have mental images, based on prior experience, of the engineering personnel who read specifications. 132 Table 5 (cont'd.) RESPON- DENT AWARENESS OF USERS 10 Writers have from very little to average awareness of readers. 11 The writers of proposals and reports are not aware of readers' needs. 12 Writers are aware only if they are project engineers. 13 Writers are not aware--they need a broader appreciation of the total program. 14 Writers have some close association with end users--they have a good idea of what the customer wants although they sometimes ignore customer requirements. 15 The end user may be a pilot, a maintenance person, the airline, an engineer at Boeing, or an engineer at LSI/ID. End users have various levels of expertise, of which we must be aware. Somewhere in the system, we try to account for all of their needs--we in the Systems Department believe that we should take into account all of these groups in stating the system's requirements. 133 QUESTION 5: "DO your writers have contact with end users before or while they write? And does this contact or lack of contact affect document quality?" Respondent 5 mentions the "longstanding relationships reinforced by telephone communication" between some writers and end users (see Table 5). Question 5 assesses the degree to which similar contact is common (see Table 6). Although some managers and coordinators assert a high level of contact (res. 5, 7, and 15), most indicate that commu- nication between the writers and their readers is limited. When writers work with a commercial customer like Boeing, they often converse with engineers and pilots (res. 4 and 15). But when they write for military customers, most "writers of specifications have contact only with end users internal to LSI/ID" (res. 11). Writers do have some contact with an external audience through the design review meetings. Such meetings may "not affect document quality," but at least make "the end user better informed" (res. 2, 3). Sometimes, such meetings permit the customer "to dictate much of the document content" and facilitate "writers' meeting the end users' needs" (res. 2). On the other hand, many writers have no direct contact with their readers through these meetings: "Writers' contact with the end user is mostly through the lead project engineer" or the "lead writers" (res. 12 and 11). Lead engineers' or lead writers' mediation has its benefits: these individuals can best prescribe "an appropriate struc- ture within which those under them write" (res. 1). Theoretically, the 134 informed lead project engineer can translate the customer's needs into consistent guidelines that many writers working under him may follow and insure "technical accuracy, consistency among writers, and meeting contractual format obligations" (res. 12). The lead project engineer can also serve as an information buffer between the writers working under him and the customer, who "should not get information for which he has not paid" (res. 14). Most managers and coordinators agree that contact between writers and the customer is limited--generally mediated by way of meetings between the customer and the lead project engineer. When managers and coordinators address the effects of this indirect contact on document quality, they generally dismiss it as small. Writers often have limited contact with their audience--and their managers and coordina- tors often consider such contact unnecessary. 135 Table 6. Question 5: "DO your writers have contact with end users before or while they write? And does this contact or lack of contact affect document quality?" RESPON- DENT DEGREE OF CONTACT/RELATIONSHIP TO QUALITY Writers generally do not have such contact, but this lack probably does not affect document quality. Engineers must meet standards dictated by an entire group of people and do not individually select a form designed to meet the end users' needs. Lead engineers meet these needs by prescribing an appropriate structure within which those under them write. Writers have some contact with end users at design review meetings. For the Performance Data Computer, this contact probably did not affect document quality, but it made the end user better informed. For the Flight Management Computer, this contact allows Boeing to dictate much Of the document content and facili- tates writers' meeting the end users' needs. Writers have contact with end users in design review meet- ings, but this contact does not affect document quality. The engineer-to-engineer basis for communication in a design review translates into engineer-to-engineer writing. Writers have little contact with end users, but they do have contact with engineers at Boeing. There is no such contact with end users in the Air Force and Navy. This low level Of contact has no effect on document quality. Writers tailor their writing to the end users' needs. There should be a high level of contact, but the actual level varies. Prepublication conferences and reviews with both military and commercial customers provide for much contact, so the customer is rarely surprised at the final product. This contact may not result in improved quality, but it increases acceptance. 136 Table 6 (cont'd.) RESPON- DENT DEGREE OF CONTACT/RELATIONSHIP TO QUALITY 10 11 12 13 14 15 There is limited contact: informal meetings in Grand Rapids, but no contact in the actual operating world. LSI/ID sends its people out on flight tests to see this operating world. Writers have little contact, but the lead project engineer has contact and relays information, so no problem results. Writers have contact, and a slight improvement in writing quality results. Writers of reports and proposals have little contact with end users (except for lead writers). Writers of specifications have contact only with end users internal to LSI/ID. Writers' contact with end user is mostly through the lead project engineer. But this lead engineer's primary concerns are technical accuracy, consistency among writers, and meeting contractual format obligations. Contact between writers and end users has minimal effect on document quality or writers' approach. Writers have little contact with end users. Writers have little contact with end users, but this is desirable because the customer should not get information for which he has not paid. Yes, all the time: Boeing has pilots working with us all of the time. 137 QUESTION 6: "In the projects with which you work, is contact between writer and end user a practical possibility?” In general, managers and coordinators question the practicality of contact between writer and end user (see Table 7). Respondent 1 summarizes the general trend of their response: "Written communication is possible, but oral communication less likely, except at occasional reviews." Respondents 4, 9, and 13 question the practicality of any contact between writer and reader. Seven respondents qualify the practicality of such contact: this contact is costly (res. 2); this contact involves security risks (res. 14); and only lead project engi- neers and writers who participate in periodic briefings have such contact (res. 3, 6, 8, 11, and 12). But several respondents describe frequent discussion between the writer and audience: "Such contact is practical and occurs constantly via telephone communication" (res. 5); writers of user documentation (from Technical Publications) receive feedback from customers who run through the procedures described in Operator or maintenance manuals "with a copy in hand" (res. 7); phone communication and a coordination memo system operate between writers at Lear Siegler, Inc./Instrument Division (LSI/ID) and their counterparts at Boeing (res. 10); and "This contact [between LSI/ID and Boeing] is very definitely possible and occurs frequently" (res. 15). The replies of respondents 10 and 15 may actually reflect contact only between upper-level writers at LSI/ID (particularly those in the Systems Analysis Department, who write Part 138 I specifications) and end users at Boeing, not between all writers at LSI/ID who work on Boeing projects and their audience in the Seattle firm. As respondent 3 suggests, "For the Flight Management Computer System, half of the writers involved have had direct contact with counterparts at Boeing, but the other half (entry-level people) have had little contact." Contact between writer and reader involves cost and risk to the company. Yet, despite these barriers, contact does exist, at least, within the framework of some projects, between upper-level writers and their readers. Generally, such contact more Often occurs in commercial projects for the Boeing Corporation than in projects for the US military or its subcontractors. The lead writer or lead project engineer is more likely than other participants in a software project to have direct contact with the reader. The average writer has mediated contact with the reader--through the lead project engineer. 139 Table 7. Question 6: "In the projects with which you work, is contact between writer and end user a practical possibility?" RESPON- DENT POSSIBILITY OF CONTACT 1 Written communication is possible, but oral communication less likely, except at occasional reviews. 2 Such contact is possible, but whether it is likely depends upon how much the company is willing to spend on documenta- tion. 3 For the Flight Management Computer System, half of the writ- ers involved have had direct contact with counterparts at Boeing, but the other half (entry-level people) have had little contact. 4 Such contact is not practical. 5 Such contact is practical and occurs constantly via tele- phone communication. 6 Such contact is usually practical when users come in for a briefing. 7 Such contact occurs through required conferences during the writing cycle. Technical Publications sends verification copies before printing, and the customer actually runs through a procedure with a copy in hand. 8 Contact is practical, but not always present: A tester from an Air Force support group will brief writers here on the Fuel Savings Advisory System. On the other hand, a procurement agent generally just consults a DID (Data Item Document), which spells out format, to evaluate a document--he has no concept of content, but knows what paragraphs are necessary. 9 Chaos would result if all members of a writing team were involved in contact. 10 Phone contact with Boeing is possible and likely. A Boeing requirements and coordination memo system documents discussions between LSI/ID and Boeing. 140 Table 7 (cont'd.) RESPON- DENT POSSIBILITY OF CONTACT 11 Contact is usually impractical, except for the lead project engineers. 12 For the lead project engineer, such contact is a practical necessity, but this contact centers around technical accom- plishments (computer programming), not documentation. For the lead project engineer, this contact allows knowledge of customer requirements--the customer does not specifically know how to state these requirements, but the project engi- neer develops them out of discussion with the customer. The customer usually cannot understand the technical aspects of documentation--users within the company often can, but time constraints often prohibit them from providing feedback to the lead engineer. Writers under the lead engineer rarely concern themselves with audience, whether external or internal to LSI/ID. 13 Such contact is not feasible because of the manner in which LSI/ID operates. 14 Contact is sometimes possible if the writer realizes the risks involved in disclosing proprietary information. 15 This contact is very definitely possible and occurs frequently. 141 SUMMARY Table 8 includes data drawn selectively from the responses to questions 1 through 6. The column headings list the types of writing tasks respondents mentioned in response to question 1. Rows 1 and 2 distinguish between the lead writer's and writer's awareness of the "user" (a term encompassing both internal and external parties) as respondents describe these levels of awareness. Row 3 shows how respondents rate the importance and practicality of contact between writer and reader. The tabulated survey results suggest that lead writers generally have a higher awareness of the user than the average writers working under them. Respondents' ratings of lead writers' awareness are higher than their ratings of writers' awareness. (Compare row 1 and row 2.) Though respondents rate lead writers and writers on the same level for several kinds of writing tasks, they clearly give lead writers a higher rating for the proposal, the military Part I, and the military Part II. The table shows how different types of writing tasks and various affiliations with customers influence awareness of the audience. Because only two respondents mention proposal-writing (res. 11 and 5), the results for this task are inconclusive. The wide range between the responses of these two individuals makes these results even more un- reliable. 142 flaws; so .aswcua .SOHV mmuaoumsm mo mHo>OH umonu ou mama aw“: cunumuum HOORO Op uoqmow swam IsomamaH .eaz awsm 303 .3m: 303 Insawsm .m flawsa so .Edwvoa .3OHV mum: mo mama .woa mmusuumsm uaowo ou nwfln mo Hm>uH awsm -AumsmaH .smz awn: son son on son .msaussz .N flaws: so .Edfiwma .sosv mow: mo mmonuumsm «use .sme awn: mo Hm>mH uauflu OH on :wfin op .muuuwus nwfl: IwwmsmcH .vuz nwwm 30H .wuz asfiooz CODA .H HH .um H .um HH .um H .um Hands: m.noumuumo no unmasoon Hmwouuaaou humuwafiz Hmwomoum mommaouawmz umuB newpmowwwommm game wasusuz muflzmum >m>u=m unu mo >um885m < .w assay 143 Because most respondents mention specification-writing while answering questions 2 through 5, the results for this task are more conclusive. Respondents clearly suggest that lead writers and writers Of commercial specifications have a higher awareness of the audience than writers of military specifications. (Compare their ratings for these tasks in the central four columns of Table 8.) Respondents also indicate that writers and lead writers of Part I specifications generally have a higher awareness of the audience than those who work with Part 11's. The managers and coordinators of commercial specifica- tion writers attach greater significance to awareness of the audience than do managers and coordinators of those who write military specifi- cations. Test documents are common, but the survey provides insufficient data for conclusions about their writers. On the other hand, the survey provides ample data for conclusions about writers of maintenance or operators' manuals. Of the managers and coordinators surveyed, only respondent 7 supervises these writers. But respondent 7 and four other respondents who mention the maintenance and operators' manuals agree that these writers and associated lead writers have a high awareness of the end user (a pilot or ground maintenance person who will use the documentation to learn complex procedures). Managers and coordinators attach a high level of significance to these writers' awareness Of the user because their documents (by definition) must serve the need for accurate, understandable, and practical information. 144 In general, respondents explain that participants' awareness of the user varies with their roles in the writing process (writer or lead writer), the kinds of tasks they do (specifications, user documents, etc.), and their affiliations with projects (military or commercial). Managers and coordinators attach more weight to this awareness in the writing of user documentation than in specification-writing, and in commercial as Opposed to military projects. In listing writers' weaknesses, five managers and coordinators in some way identify a limited sense of purpose as a weakness in writers, and one identifies a limited sense of audience. Although some managers and coordinators recognize a limited sense of purpose as a problem, respondents are far from arriving at consensus on this point, and they generally indicate that the degree of contact between writers and their audience is not a critical factor. Yet respondent 15 generally rates his writers' awareness of the audience high and considers it very important. This respondent describes how writers under him use the adaptation of DeMarco's Struc- tured Analysis described in chapters 1 and 2 to achieve a product the user may better understand. Respondent 15 also explains that the writers who use this method have high levels of contact with their counterparts at the Boeing Corporation, LSI/ID's prime commercial customer. This level of contact may explain managers' and coordi- nators' general sense that such writers have a better sense of the user than those who address a military customer. CHAPTER 4 The survey of managers and coordinators suggests that the degree to which writers and lead writers are involved in the writing process, the kinds of writing they do, and their project affiliations influence their awareness of audience. In particular, lead writers are more likely than writers to become aware of their audience. Writers who compose user documentation are more likely to develop an awareness of the user than those who write specifications. And participants in commercial projects generally know the user better than their counter- parts in the military sphere. This chapter will record a survey of 15 lead writers and writers, administered immediately following the first survey, in winter and spring, 1985, that tests managers' and coordina- tors' hypotheses about these individuals. INTERVIEWS WITH WRITERS AND LEAD WRITERS Respondents in the survey of managers and coordinators provided a list of writers and lead writers for further interviews. From this list, I selected a relatively even number of base-level engineers and section-level managers (see Table 9). Seven of the respondents were "engineers"; one was an "engineering associate"; and seven were "man- agers." As their responses to survey questions will show, all re- spondents had experience as either writers or lead writers. 145 146 Table 9. Writers’ and Lead Writers' Positions and Affiliations with Projects RESPONDENT POSITION AFFILIATION 1 Manager Commercial and military 2 Software engineer Military 3 Section manager Military 4 Section manager Commercial 5 Software engineer Military 6 Section manager Military 7 Section manager Commercial and military 8 Section manager Commercial and military 9 Software engineer Military 10 Senior engineer Military 11 Software engineer Commercial and military 12 Staff engineer Military 13 Senior engineer Military 14 Section manager Commercial and military 15 Engineering associate Commercial and military 147 The roster reflects a less-even balance between participants in the military and commerical spheres (see Table 9). One respondent works in commercial projects, eight serve military projects, and six participate in both commercial and military projects. This chapter reports these respondents' answers to seven survey questions, administered in the same manner as questions for the first survey, approximately one month later. Each section of the chapter summarizes the general response to one or two questions, then para- phrases all respondents' answers in tabular form. Most questions probe writers' and lead writers' senses of purpose by asking these individ- uals to provide convincing rationales for their methods of composition. Questions 1 through 4 particularly investigate how writers' and lead writers' planning activities, writing strategies, and revision techniques express concern to establish audience and purpose. By asking writers to identify the methods they use during these phases of writing and to identify their rationales for these methods, these questions investigate whether they employ these techniques with some sense of purpose. Questions 5 and 6 further probe writers' sense of purpose by asking them to explain their rationales for using figures and tables to support or replace narrative text. Question 5 investi- gates how writers generally explain their use of figures or tables, and question 6 specifically discovers how they evaluate the structured approach to writing specifications, in which writers use figures in place of narrative text throughout most of a document. And question 7 148 discovers to what extent writers' awareness of the customer is indeed a function of their levels Of involvement in the writing process, the kinds of writing they do, and their affiliations with projects, as managers and coordinators suggest. As their answers to these questions will show, these writers and lead writers generally have strong senses of purpose. Respondents generally demonstrate strong senses of purpose for the techniques they employ throughout prewriting, writing, and revision phases, and they can generally provide intelligent rationales for using figures or tables. In general, respondents' answers reinforce managers' and coordinators' observations: that lead writers are generally more aware of the audience than those who work under them; that writers of user documentation are more likely than writers of specifications to develop a sense of the audience; and that writers who address commercial customers have a stronger sense of the audience than their counterparts in the military sphere. QUESTION 1: "Please describe the forms of writing which you do for each project." Respondents in the second survey explain that they do a wide variety of writing for different categories of users (see Table 10). Two writers identify "proposals," and four mention user documenta- tion--texts that require the writer to approach the customer with a persuasive appeal or informative explanation. Eight mention 149 specifications and test documents, texts directed at the customer but serving internal users as well. Nine respondents explain that they compose texts for internal use that the customer never sees, for instance, interoffice communications (IOCs), reports, users' manuals, and training materials. These respondents must compose many kinds of texts for at least two kinds of readers--internal and external. Most respondents indicate that they are versatile writers who compose for a wide variety of purposes and audiences. Respondent 4 writes "everything from interoffice communications addressed to engineers here to technical specifications addressed to the customer." Respondent 6 writes anything from training materials for internal use to operating instructions for pilots, to maintenance manuals for mechanics. Respondent 7 writes monthly status reports and communi- cations to fellow members of his section, as well as "reports of defi- ciency or corrective action to the customer." Respondent 8 writes research and development reports for internal users and conference papers, patent disclosures, and proposals for external parties. While seven respondents mostly write Part I's, Part 11's, or test documents, the remaining eight write a wide variety of texts, addressed to both internal and external parties. The variety Of writing tasks respondents do and the several audi- ences they address suggest their sophistication about purpose and audience. 150 Table 10. Question 1: "Please describe the forms of writing which you do for each project." RESPON- DENT FORMS OF WRITING DONE Mostly work internal to LSI/ID: reports, presentations, IOCs, letters, users’ manuals, and articles in newsletters. Part I and Part II specifications. Test procedures and reports. Part I (requirements specification): More top-level and wordy than Part 11. Includes "timing and sequencing" which does not fall neatly within the domain of Structured Analysis. Has many diagrams fully explained in words. Part II: Uses automated generation of paragraph numbering and titles (for every Computer Program Component, one paragraph and several subparagraphs). Includes handwritten text within this automated frame- work. Everything from interoffice communications (IOCs) addressed to engineers here to technical specifications addressed to the customer. Proposals. Coordination memos to customers. Monthly reports to management. Performance evaluations for personnel. Memos. Part I's (a little); Part 11's (a lot). Users' manuals. Material for training courses. Technical manuals for LRUs (line replaceable units) on airplanes. Pilots' Operating instructions. Aircraft maintenance manuals: Operational and organizational manuals for testing boxes on an airplane. Intermediate manuals for boxes pulled off an airplane. Fault isolation procedures for circuit cards within boxes. 151 Table 10 (cont'd.) RESPON- DENT FORMS OF WRITING DONE (cont'd.) 10 11 12 Theories of Operation, which explain how boxes work functionally (block diagrams, schematics, timing diagrams, narrative text). Illustrated parts breakdowns. Monthly status reports. General communications to section. Reports of deficiency or corrective action to customer. Corrective action requests to internal pe0ple. Procedures, plans, handwritten records, and fill-in-the-blank forms. Reports (e.g., annual internal research and development report to the government in standard format). Technical descriptions of tests performed (mostly hardware). Papers on the Optical Rate Sensor (ORS) for conferences-- used with view graphs on slides. Patent disclosures on ORS--used by patent attorney and imitating attorney's style. Proposals which adhere to required format but use sale-oriented presentation geared to the customer's needs. Memos, summaries of current work. Test documentation. Internal communication. Part 1's and Part II's. Comments in code. Final reports, coauthored papers, and conference papers for ADO. Test procedures. Part II's. Proposals. Tutorial papers (final reports). Letters. Interoffice communications. 152 Table 10 (cont'd.) RESPON- DENT FORMS OF WRITING DONE 13 14 15 Part I's. Software verification test plans. Internal documentation for department. Commercial: Air Transport Association (ATA) specifications. ATA-100 component maintenance manuals (equivalent to overhaul manuals in military). P-3B: Organizational, intermediate, and overhaul manuals. PNCS and FMCS: Pilots' guides tabbed for quick reference. Pictures of CDU (how to access and use). PDC: Pilots' guides and pocket guides (memory joggers). Part 1's and Part II's. 153 QUESTION 2: "Please describe methods which you use to plan before you write. Please describe aids which you use to formulate ideas or expressions as you write. Please describe methods which you use to revise after you write.“ Respondents discuss three planning activities that directly re- flect their concern for the audience (see Table 11). First, several explain how they study generic guidelines or models. Respondents 3, 14, and 11 study military and commercial standards for the format of engineering documentation or models for imitation. These writers who study guidelines and models anticipate an audience that expects con- formity to the recognized standards for format. Second, several de- scribe how they read customer requirements. Respondents 2, 3, 4, 6, 11, 14, and 15 review the Data Item Description, the customer's outline of the document to be written. Writers who review the Data Item De- scription anticipate that the customer expects them to follow his out- line. Third, demonstrating an obvious concern for the reader, another writer states that he thinks "about the intended point and audience" (res. 5). Respondents discuss three writing strategies that similarly express concern for the audience. First, several copy or imitate existing text, partially to save time and energy, but also to insure that they use a format the customer has previously approved. Respond- ents 2, 4, and 11 develop new writing from Old by wholesale copying or, at least, substantial imitation, to make certain that the new text resembles previously-approved samples. Second, others study existing 154 customer-approved guidelines; for instance, respondent 15 uses "data dictionaries" (see chapter 1), developed internally, but sanctioned by the customer, to define the basic elements of each computer process she describes. She is thus certain to use a diction the customer under- stands and approves. Third, other respondents test the text with the intended audience during the course of writing. For instance, respond- ent 6 reviews the text with the customer at intervals to be certain of satisfactory progress. Finally, respondents describe three approaches to revision that parallel their prewriting and writing strategies and express a similar concern for the audience. First, some writers check the final product against pre-existing models; for instance, respondents 2 and 11 study the pre-existing data again to verify that the document reflects its models. Second, other writers consult customer-approved guidelines. Respondent 4 checks the text against the customer-approved requirements dictionary. Third, still others test the text with a simulated audi- ence. Respondents 3 and 13 specifically attempt to emulate the re- sponse of the intended audience by reading "as if someone else wrote" the documentation (res. 3). Respondents mention many other kinds of prewriting, writing, and revision activities, for example, using standard outlining procedures, imitating spoken language, and using the spelling checker on the VAX Computer. But those summarized above best reflect respondents' attempts to satisfy the audience through the study of guidelines or models, reading of requirements, and thought about the intended user. 155 The number of respondents who mention these strategies is one indica- tion that writers and lead writers at LSI/ID are aware of the audience. 156 Table 11. Question 2: "Please describe methods which you use to plan before you write. Please describe aids which you use to formulate ideas or expressions as you write. Please describe methods which you use to revise after you write." RESPON- DENT METHODS 1 Before: sketching, outlining with headings, ordering these headings. While: Moving blocks around, leaving blocks to be filled (making full use of text-editor capacity). For long articles-~writing ideas first, ordering later, throwing miscellaneous ideas at the bottom of a file (every engineer should have a terminal, which allows this flexibility). After: Proofing on paper rather than at the terminal. Using edit/journal file on the VAX Computer (which records the processes and products of editing on magnetic media). Using VAX for all revisions is problematic--thoughts race ahead of the computer because computer response time is slow. 2 Before: review of existing data, note of where changes must be made, reading of DID (Data Item Description). During: modification of "existing stuff." After: review of pre-existing data. 3 Before: unconscious methods, study of format guidelines such as military standard. During: unconscious methods, if any at all. After: letting a document "sit" a few days, then going back to reread it as if someone else wrote it. 4 Before: Review of existing documentation, including requests for the present item. Thought process about format. Outline of notes to be referred to while writing. For Structured Analysis, use Of the Requirements Dictionary on the VAX Computer. During: review of existing documentation. 157 Table 11 (cont'd.) RESPON- DENT METHODS 4 After: (cont'd.) Use of the text editor, including SPELL (the spelling checker on the VAX Computer). Use of the Requirements Dictionary on the computer for structured writing. Print-out for proofing before sending out. 5 Before: Thought about the intended point and audience. Development of an outline with headings that will become ”headers" for paragraphs. During: Use of the VAX Computer almost entirely--no paper and pencil. After: Use of the editor on the VAX, but only SPELL (not other functions such as check for passive voice, sexist language). Mark-up of printed copy, but any extensive changes directly on VAX editor (to avoid transfer from paper to VAX). Rearrangement of sentences mostly by ear (although respondent knows some grammatical terminology and usage guidelines, such as avoidance of the passive voice and final prepositions). 6 Before: Cost estimating-- Definition of requirements (what kind of copy must you deliver?). Determination of format (to what specs must you conform?). Knowledge of depth (organizational, intermediate, or depot?). Projection of necessary test equipment (automatic or manual?). Identifying major elements-- Theory of operations. Test procedures. Illustrated parts breakdowns. Physical repair procedures. Fault isolation procedures. 158 Table 11 (cont'd.) RESPON- DENT METHODS 6 Outlining task-- (cont'd.) Identification of subject areas and subtopics. Definition of illustrations (number, difficulty, manual or automated). Schedule of tasks, including participation of different groups within LSI/ID. During: Meetings of writers and editors--checking against specifications. Coordination of illustration group following detailed schedule developed above (see "Outlining task"). Customer review. Supervision of tasks by lead writer. After: Validation exercise-~going through the procedure with the equipment by following the documentation. Prepublication review. 7 Before: Roughly outlining the major points. During: Writing as the respondent would say it ("How would I say it?"). After: Reading it over ("Does it sound good?"). Finding glaring errors of phraseology and redundancy. Erasing the penciled draft and inserting alternate/additional words. 8 Before: Creating a gross outline (or receiving it from boss). During: Following this outline (in the case of a proposal, largely dictated by the customer). After: Rewriting--c1eaning up or reordering paragraphs to improve step-by-step logic for the reader (by addition Of lead-in’s or transitions). 159 Table 11 (cont'd.) RESPON- DENT METHODS 10 11 12 Before: Outlining the document, usually with the main points dictated by the customer. Outlining the Test Plan by following the structure of the test. During: Filling in the outline using cut and paste. After: Using the spelling check on the VAX Computer. Reading for smooth flow. Before: Establishing a reason for writing or a thesis. Writing an outline. During: Filling in the outline. After: Rereading-- "Does it sound good?" "Are English and grammar sound?" "Could it be more concise?" Before: Finding a document similar to the one to be written and establishing a pattern for the new document. For Boeing, using a customer-established format. During: Imitating the existing document and using similar terminology. After: Checking for accuracy. Reading someone else's document and checking for consistency. Before: Outlining (for extensive document). Looking at the figures to be used before the details of writing. During: No conscious aids. 160 Table 11 (cont'd.) RESPON- DENT METHODS 12 After: (cont'd.) Usually while editing other people's proposals-- Changing the passive to the active voice. Changing intransitive to transitive verbs. Changing the impersonal to "we" or "LSI/ID." 13 Before: Laying out an outline of the introduction and section headers. During: Filling in the blanks of the outline with details and specifics. After: Taking the viewpoint of another reader or the intended audience-- "If I were reading it..." (first time revision) "If the intended user were reading it..." (second time revision) Breaking up long sentences. 14 Before: High-level planning-- Matching skills to the job. Assigning a project engineer to write. Writing statement of work for the writers based on the customer's stated need, including the details, needed information (writers' travel sheet), a schedule, and a milestone chart. Writers' planning-- Using specifications and drawings as input data. Writing and outlining the manual according to military or commercial specification, telling what goes where and what figures/tables will appear. During: ' Starting with functionalization--studying drawings and making scratch drawings for as long as two months before actual writing. Drawing functional drawings and a theory Of operations. 161 Table 11 (cont'd.) RESPON- DENT METHODS 14 After: (cont'd.) At planned steps-- ~Project engineer consults with individual writers. Project engineer marks up documentation section-by-section. Editorial group checks English and specification compliance. Test group validates against actual procedure. People in other departments review. 15 Before: Studying Software Requirements Documents guidelines. Using on-line data bases and customer specifications. During: Referring to data dictionaries. After: Using the editor on the VAX Computer. 162 QUESTION 3: "Do you use storyboards? Please describe your use of storyboards. Have you participated in a walkthrough? Please describe it." ~ Many respondents are unfamiliar with storyboards, but three describe their use in some detail, and two identify their purpose: to assess proper fit between elements of a text (see Table 12). Respondents 8 and 12 describe how proposal-writers gather around a storyboard, a wall hanging split into numbered sections, each of which represents a major section of the proposal. In the first phase of planning a proposal, writing team members fill each section with a single figure and a "one-liner" describing the figure or the major section of the proposal. The lead writer copies these storyboards and distributes them to a panel of experts, who mark them up before a second draft. Respondent 12 explains that the storyboard helps "the ' in other writer of a section [in a proposal] clarify what he is doing,’ words, discover how his section fits into the logic of the whole proposal. Respondent 14 describes how storyboards help technical writers prepare computer training materials for pilots. In group sessions, writers present storyboards, each one representing a frame of planned computer instruction, and each one including both an illustration and accompanying text. By this means, writers may help one another judge whether the sequence of frames fits together logically. 163 Respondents disagree about the specific character and timing of a "walkthrough." For respondents 2, 3, 5, and 7, a walkthrough is a discussion of coding, not text; for respondents 4, 6, 8, 9, 10, 12, 13, 14, and 15, it is a discussion of text. Respondent 8 says this "re- view" occurs before the text is even written; 9, 10, 13, and 15 say this review occurs while the text is in process; and respondents 4, 6, 12, and 14 say this review occurs in the penultimate or final stages of writing. Yet all describe a walkthrough as a discussion through which two or more people review a section of code or text, and all agree about its general purpose: to review a particular piece of work, whether writing or programming, and determine whether the parts con- tribute to the logic of the whole in a manner the audience can under- stand. By working through a text "cover to cover" with another indi- vidual, an author understands "how the logic of the document meets customer requirements and document purpose" (res. 4). By walking through a text "part-by-part" with an audience of several people, the author discovers what "parts they do not understand"--what parts require clarification (res.15). The writer makes "sure that one or two others read it in the same manner as its author" (res. 9) as they walk through it "section-by-section" (res. 14). Writers and lead writers who use storyboards and walkthroughs thus recognize the underlying purposes of these procedures: to insure that a text reflects consistent logic in the relationship between its parts 164 and that this consistent logic is apparent to its audience. Respon- dents' concern for internal coherence is evidence that they have clear senses of aim. Like Kinneavy, these respondents understand that the organization of a text must clearly reflect its dominant logic in order for the text to achieve its aim. 165 Table 12. Question 3: "Do you use storyboards? Please describe your use of storyboards. Have you participated in a walkthrough? Please describe it." RESPON- DENT USE OF STORYBOARDS OR WALKTHROUGHS 1 The respondent does not use these methods. 2 The respondent does not use storyboards, but has participat- ed in walkthroughs, these to coordinate coding, not to improve documentation. In the respondent's experience, the review of documentation is through a document coordinator, not a walkthrough. 3 The respondent has seen storyboards used for proposal writing, but would not know how to use one. The term "walkthrough" is a broad concept, but applied to coding, it usually means a case where one person reviews what another has done line-by-line--the reviewer attempts to understand the salient parts of code, and the writer attempts to explain why he wrote them as he did. The writer, not the reviewer, generally identifies the prob- lem: "You understand your writing better by explaining it." 4 The respondent does not use storyboards, but has partici- pated in walkthroughs. In a walkthrough, the author (usually a senior member of staff) explains a document "cover to cover," elucidating how the logic of the document meets customer requirements and document purpose. 5 The respondent is familiar with the movie industry's use of storyboards, but does not know how to apply them at LSI/ID. He applies the term "walkthrough" entirely to walking through coding with another individual, not to walking through narrative text. 6 Storyboards: The respondent has no experience with storyboards. Walkthroughs: He uses walkthroughs for validation and verification exercises, which usually involve one or two from LSI/ID, one government representative, and sometimes a team from a prime contractor such as General Dynamics. 166 Table 12 (cont'd.) RESPON- DENT USE OF STORYBOARDS OR WALKTHROUGHS 10 11 The respondent does not use storyboards. The respondent uses walkthroughs for cursory, not detailed, reviews of coding with two or three people, sometimes with the customer, but not Often. Storyboards: The respondent does not like storyboards because they are too time-consuming and detailed. The respondent uses storyboards with numbered sections, one to a storyboard, each to be filled by one-liners describing the section contents or describing figures. The lead writer copies these storyboards and dis- tributes them to experts who critique them and mark them up for a second draft. Walkthroughs: People working on a proposal come together in one room, listen to a briefing on the background for the pr0pos- al, and receive assignments to write specific portions. A lead person reads the Request for Proposal, generates a basic outline of sections, and assigns sections to others. The respondent does not use storyboards. A walkthrough involves going through a document in detail and making sure that one or two others read it in the same manner as its author. The respondent has not used storyboards but has followed a proposal outline with a thesis. A walkthrough involves practicing oral presentation of over- heads. The respondent has not used storyboards or walkthroughs. 167 Table 12 (cont'd.) SESEON- USE OF STORYBOARDS OR WALKTHROUGHS 12 Storyboards: The respondent has used storyboards to prepare proposals. Storyboards involve sections with the "under headings" of the outline and rough sketches of figures. Storyboards have been used on the wall, but have proven overly time-consuming in this application. Storyboards do help the writer of a section clarify what he is doing--on the storyboard he must express what he will do in his part. Walkthroughs: A walkthrough involves a review of a storyboard, a top-level review of a proposal. In a walkthrough, reviewers present summaries of their respective sections of a proposal. 13 The respondent does not use storyboards. In developing a design, the respondent walks through a pro- cedure with another person. To support the walkthrough, he uses view graphs (not direct- ly based on a text, but developed from scratch). 14 Storyboards: Background--in training, PLATO system lessons show the pilot how to operate a system much as pilots' guides do. Storyboarding is used to plan these lessons: a story- board with an illustration and accompanying text is placed on the wall and critiqued. Storyboards insure that the planning is over before programming begins. Walkthroughs: At planned intervals in writing, the project engineer consults with individual writers and marks up manuals section-by-section. 15 The respondent does not use storyboards. The respondent "walks through" specifications--she explains a specification part-by-part while an audience of several people expresses understanding or lack of understanding, and she then clarifies the parts they do not understand. 168 QUESTION 4: "When and why do you explain or discuss printed material aloud?" Respondents have already discussed their use of walkthroughs--one instance in which they explain or discuss printed material aloud. But most repondents also describe other circumstances where they explain texts orally (see Table 13). Respondents say they explain or discuss texts for several pur- poses. Usually, each purpose implies either an internal or external audience. A number of respondents explain or discuss texts for the purpose of sharing knowledge, primarily in the context of an internal audience. Respondents 1 and 8 explain technical reports to other department members to disseminate current technical information. Respondent 5 explains text aloud to fellow section members to clarify their ques- tions about a software program. Respondent 11 receives information from fellow writers by asking them to clarify his questions about texts they have written. Other respondents discuss printed material with the customer to guide their revision of the text or the process it describes. Respond- ents 4, 9, and 10 discuss a specification with a customer to verify that the customer understands the stated requirements; if the customer does not, then these respondents must revise the text. Respondent 6 explains training material to the customer for the same reason: to receive the customer's evaluation of the texts and revise accordingly. 169 Respondent 7 presents plans and procedures to receive the customer's approval of quality control procedures; if the customer does not approve, the procedures must change. Respondents may also discuss text with an internal audience to guide revision. Respondent 4 explains a specification aloud to a fellow software team member so that he and the other member may together revise the text. In Technical Publications, respondent 14 explains, lead writers and writers read portions of training material to one another and discuss the need for revision. Respondents explain or discuss printed material aloud for several audiences and purposes. In all cases, they are able to explain why they present the material orally. When respondents present texts to an external audience orally, they usually do so to aid their revision of document content or form. Respondents orally present texts to internal audiences either to aid revision or to share information. 170 Table 13. Question 4: "When and why do you explain or discuss printed material aloud?" RESPON- DENT ORAL DISCUSSION OF PRINTED MATERIAL The respondent explains reports aloud to one, two, or three individuals and presents papers to an audience. The respondent does not normally explain printed material aloud, but the coordinator of a project does give him oral directions before he writes. The respondent explains printed material aloud during a review of a document with a customer in a less detailed manner than during a walkthrough. He uses slides to highlight the main points within complete documents--the customer sometimes requests changes. The respondent feels better if the customer responds to the presentation in some way--this demonstrates that the customer is technically competent. Specification reviews: The respondent explains printed material aloud to a customer--the customer and respondent raise questions. The respondent and customer make a general attempt to arrive at a mutual understanding of what the require- ments specification calls for--their versions may be contradictory, and a revision may result. Problem reports (PRs): Two members of a software team discuss a particular problem involving meeting or interpreting a particular requirement. These members discuss whether the problem exists and how to resolve it--they make a report to the customer or management, recording the resolution of the problem. A peer in the section asks, "What do you mean here?" The respondent then explains what he has written. If he finds a segment of documentation that sounds funny or cute, he shares it with a cubicle mate. He explains segments of code in walking through them with other individuals--these individuals share his approximate level of expertise but lack knowledge of the specific segment he has coded. 171 Table 13 (cont'd.) RESPON- DENT ORAL DISCUSSION OF PRINTED MATERIAL 10 11 12 The respondent explains printed material aloud to the customer during validation or verification exercises or during prepublication reviews. As the representative of Software Quality Assurance, the respondent must explain procedures or plans to customers during customer audits--this proves to the customer that LSI/ID actually has done the procedures it has recorded. In Research and Development, the respondent often reads technical journals (6-8 per week) and shares articles with other department members. He also summarizes the papers from conferences and symposiums he has attended for other department members. The respondent explains material to the customer during a "walkthrough." He must translate the customer's "vague and inconsistent" statement of requirements into a more consistent and accurate statement. The respondent must then explain his restatement of require- ments orally, in terms the customer understands. The respondent often discusses contents Of a Part I or Part II specification with the customer to make sure that the specification is clear and concise. When the respondent does not understand a piece of text, he Often reads it aloud to its writer and asks, "What did you mean?" But the writer is Often unavailable. The respondent rarely reads written material aloud, but does make technical presentations using view graphs extracted from text. View graphs are better than unedited written material for making presentations because an audience tends to read ahead and pick up extraneous material when presented with long portions of text. 172 Table 13 (cont'd.) RESPON- DENT ORAL DISCUSSION OF PRINTED MATERIAL 13 14 15 The respondent uses view graphs instead of reading printed material aloud, but when anyone asks the respondent about something he has written, he then must explain it aloud. In Technical Publications, the lead writers and writers Often read written material aloud to one another, comment on one another's work, and make written notations of the need for change. The respondent tried to explain a specification to a class, but had difficulty because the specification was 15,000 pages long--this is why the structured methods are better: they eliminate unnecessary length and promote oral discussion. 173 QUESTION 5: "When and why do you use a figure or table in printed material? What varieties Of figures and tables do you use?" Many writers and lead writers present rationales for the use or nonuse of graphic aids that reflect concern for purpose and audience (see Table 14). Some writers and lead writers decide whether or not to use figures and tables by discovering whether these forms facilitate accurate representation of reality, in Kinneavyan terms, a scientific purpose. Tables may emphasize the relationships between parallel data; flow- charts may show the sequence Of a step-by-step process (res. 3, 5, and 8); a diagram may clarify the presentation of "nonlinear" as opposed to "linear" concepts (res. 9); and line drawings may emphasize the important details on hardware devices (res. 12). If the very nature of the table or figure itself promotes the accurate representation of an analogous reality outside the text, these respondents justify its use; on the other hand, if the figure or table takes the reader's attention away from the text, lets the reader draw his own conclusions, and thereby distorts the accurate representation of reality, at least one of these respondents questions its use (res. 10). Other respondents decide to use tables and figures because these forms draw the attention of the audience. In Kinneavyan terms, these writers and lead writers use these devices for informative or persua- sive purposes, to draw the reader's interest to important or surprising facts in an article or to maintain the reader's interest in the 174 persuasive discourse of a proposal. Respondent 1 uses a figure or table to draw readers to the most important concepts in technical papers. Respondent 12 uses illustrations in proposals to help "break up" the contents, to create an element of "human interest." And respondent 14 uses a "table or picture" similarly: to hold the reader's attention. Generally, respondents use figures and tables either to promote an accurate representation of reality or to draw the reader's interest. In describing their specific applications of these general principles-- concern for accurate presentation of data and effective appeal to the reader--respondents demonstrate their good sense of when and why to use a figure or table for particular purposes and audiences. 175 Table 14. Question 5: "When and why do you use a figure or table in printed material? What varieties Of figures and tables do you use?" RESPON- DENT USE OF FIGURES AND TABLES 1 The respondent uses a figure or table whenever she thinks of an appropriate one, unless the effort seems too much--she uses more figures and tables in papers than in memos. When she reads articles herself, she often ignores the text and looks at the graphics, so she naturally expects her readers to do likewise. She uses line, pie, and bar graphs. 2 The respondent uses a figure or table if it is easier to understand than narrative text because of the volume of data--the columns of a table make it possible to avoid a 20-line sentence. Specifications dictate the presence of some figures and tables--timing diagrams, flowcharts, tables, block diagrams of functions/subfunctions. The rest of the figures and tables are by choice. 3 The respondent uses a figure when a graphic representation would help relay information to the reader. He uses a table to show a pattern in itemized material and thus facilitates rapid comprehension. 4 The respondent uses a figure to provide a simple portrayal of a configuration, to illustrate a multiplicity of interconnections ("one picture=one thousand words"), and to augment textual material. He uses a table when this format is an easier way to present information. He normally uses data flow diagrams, control flow diagrams, control tables, schematics, filter diagrams, cockpit/system interconnects, and hardware block diagrams. In problem reports (PRs), he uses maps and pictures to por- tray an aircraft situation or flight plan. He uses many tables in Part I's, PBS, and test documents. 5 To avoid using a lengthy prose narrative, the respondent substitutes a graph or diagram ("worth 1000 words") that explains a very complex concept in a few words. To explain a step-by-step process, he uses a flowchart. 176 Table 14 (cont'd.) RESPON- DENT USE OF FIGURES AND TABLES 6 The respondent uses a figure or table to promote ease of understanding or to specify requirements. 7 The respondent uses a figure or table to show a "trend or pattern which has visual meaning." Organizational charts or flowcharts showing audits of li- brary controls are examples of figures that show such a pattern. 8 The respondent uses a figure or table to achieve clarity by replacing much verbiage with a picture. Tables are useful for summarizing data and making comparisons--they prevent the need for much flipping of pages. A line sketch of a test setup gives the engineer a feel for the hardware. Photos are impressive in proposals. 9 The respondent uses a figure or table whenever a picture makes a concept more clear. If a concept is linear, use text; if it is nonlinear, use a diagram. 10 A picture is worth 1000 words, but any good report will not let a figure or table take the place of words. A figure or table should merely support the text and never let the reader draw his own conclusions. The respondent uses anything from a 2- or 3-variable graph to a table Of alphanumeric data to actual pictures in combination with text. 11 The respondent follows no real guidelines-~he simply uses figures and tables in imitation of the way others do. 12 The respondent uses a task flow diagram in proposals to show how the company will organize to do a particular project. Line drawings are often preferable to photos because they emphasize the important details of hardware. Pictures are also valuable to create an element of human interest or to help break up a proposal. 177 Table 14 (cont'd.) RESPON- DENT USE OF FIGURES AND TABLES 13 The respondent uses a figure or table when trying to present a complex idea: the figure helps a person visualize the problem better. The respondent uses no bar or pie charts--mostly line graphs, flowcharts, and drawings Of circuit paths. 14 The respondent believes in using a table or picture instead of text if possible: to save words and hold attention. 15 Tables and figures are more immediately understandable than text: a picture equals 1000 words. 178 QUESTION 6: "If you are familiar with the structured approach, compare it with traditional methods of specification." The respondents here compare the contemporary approach to writing commercial Part I and Part II specifications, described in chapter 1, with the traditional approach (see Table 15). As chapter 1 explained, the contemporary Part I uses data flow diagrams, Structured English, and the requirements dictionary as its primary tools, in contrast to the extended narrative and ad hoc diagrams of a traditional Part I. The contemporary Part II uses structure charts, pseudocode, and the design dictionary in contrast to the prose and diagrams of a tradition- al Part II. One group of respondents describes the comparative usefulness of the contemporary and traditional tools: how much time and effort each may save. In the contemporary specification, the engineer, "who has little time to write," may draw a single data flow diagram or structure chart to represent a large portion of a system. The programmer may easily translate Structured English or pseudocode, "closer to actual ’ into computer code, to develop programming (res. code...than prose,’ 10). On the other hand, drawing charts for a structured specification may prove too time-consuming for the designer (res. 5). Other respondents discuss the accuracy of these tools. In Kinneavyan terms, these respondents assume the specification's scientific purpose: the accurate representation Of reality. 179 Structured English, more than narrative prose, permits an engineer to "describe a problem in unambiguous terms" (res. 10). By forcing "engi- neers to use a logical [i.e., deductive-inductive] structure for their explanations," the contemporary tools make the engineer compose an accurate description of a system (res. 12). But respondent 3 identi- fies one possible shortcoming in the accuracy of the newer method: it describes the functions of system hardware as "abstractions." Although its charts may name pieces of hardware, for instance, Control/Display Units, and show something of their relationship to other components in the system, these charts do not specify the size, shape, or internal workings of such devices. Respondents also discuss whether the contemporary tools promote orientation to the audience. Respondent 8 believes that the tools somehow improve communication in large software projects; on the other hand, he discounts their usefulness in a small-group situation, "where people sit within several feet of one another" and have sufficient contact with one another. According to respondents 7 and 9, the reader needs supplementary prose descriptions to clarify data flow diagrams, or, perhaps, supplementary conversations with the author. Para- doxically, these tools may promote better communication between the authors and audiences of commercial projects because they force the audience to approach the author for clarification of the text. 180 Table 15. Question 6: "If you are familiar with the structured approach, compare it with traditional methods of specification." RESPON- DENT COMPARISON The structured approach works: it is a better way of describing a specification than the old way. The structured approach has its advantages, but the re- spondent has not used it. The traditional specification is dictated by government standards-~it is not rigorous, not targeted to our applica- tion, and more for data processing (as Opposed to real-time) systems. Structured Analysis is more suitable to real-time needs, but it does fall short in one respect--it does not pay enough attention to specifying inputs and outputs in hardware terms; these inputs and outputs are treated as abstractions. The structured method presents the requirements situation in such a light that you have a better understanding of the functions of a particular system, how they interrelate, and the hierarchical nature of their interrelationships. This method also allows easier observation of whether you have covered all the requirements--less room for error. It requires less time and fewer pages, provides for better understanding, insures more rigor, and introduces a more convenient way to start software follow-up documentation. The respondent has found that Structured Analysis and Design help him write better. He sees the potential for using Structured Analysis/Struc- tured Design in a programmer's notebook, although he has just learned these methods. He usually uses flowcharts or calling trees--Structured Design has the advantage of showing what choices of routines are present at a particular juncture, while calling trees only tell what routines are called by a routine. The problem with Structured Design is its time requirements: it helps the writer think a problem through, but it often becomes too slow a method during the design phase, when there is much pressure to complete work quickly. 181 Table 15 (cont'd.) RESPON- DENT COMPARISON 5 The iterative approach of Structured Design helps the (cont'd.) designer improve a design gradually, and the modular approach is effective (changing one module will not "change the whole thing"). 6 The structured approach is a good method for design--it is precise before the coding even begins. 7 The traditional method missed the big picture, but its introductory sections helped. Graphics throughout may not work--there is a need to write requirements out in English. 8 Structured Analysis is useful in large software projects to help all participants understand and meet customer requirements. SA is less applicable to a small group where people sit within several feet of one another. 9 Structured Analysis lays out complex relationships in a sim- ple form. However, bubble charts should be complemented by text and other illustrations like stimulus-response dia- grams. 10 Structured Analysis requires less Of the engineer, who has little time to write. Its tools are closer to actual code and easier to maintain than prose. Structured English forces the engineer to describe a problem in unambiguous terms. 11 The respondent does not use the structured approach and has forgotten what he learned in the class on Structured Analysis. 12 Structured methods look good for generating software because they require front-end analysis and consistent organization. These methods force engineers to use a logical structure for their explanations. 13 The respondent has not used the structured methods. 182 Table 15 (cont'd.) RESPON- DENT COMPARISON 14 The structured approach is better than traditional methods because it allows more documentation on a page and is easier to understand. 15 The structured approach is better than traditional methods because it is less verbose--more easily understood than 4,000 pages of "The system shall..." 183 QUESTION 7: "In general, how do you write in order to meet customer requirements?" The response to this question confirms managers' and coordinators' assertions about writers' and lead writers' relationship to the audience: that lead writers are more aware of the audience than writers, that writers of user documentation are more aware of the audience than writers of specifications, and that writers in the com- mercial sphere are more aware of the audience than their counterparts in the military sphere (see Table 16). Lead writers often have more contact with the customer and aware- ness of customer requirements than the writers who work under them. Respondent 4, a lead writer, describes how "senior engineers" from LSI/ID meet with the customer to renegotiate the customer's original requirements. These lead writers can show that the originally-stated requirements are not in the customer's interest. In contrast, respon- dents 5 and 11, who typify the average "software engineer," have no recourse but to follow the original text. Respondents describe the advantages writers of user documents have over specification writers. Like specification writers, writers of user documents may consult a written outline of the planned text sub- mitted by the customer (res. 14), but they also have recourse to "cus- tomer review during the process of writing" and "validation exercises to test the final written product," in which a subject attempts to run through a procedure with only the user document as a guide (res. 6). 184 On the other hand, specification writers often have only a formal outline of customer requirements for guidance. Respondents 2, 3, 7, 9, and 11 follow the Statement of Work or Data Item Description, the customer-approved, paragraph-by-paragraph outline of the document. Specification writers often have no direct contact with the customer during the writing process, for other parties inside LSI/ID "work out any ambiguities in the DID [Data Item Description]" (res. 3). Specification writers' contact with the customer is thus totally indirect. Writers of military specifications have particular difficulty understanding and meeting customer requirements. Respondent 15 describes the difficulty of communication with a military customer: she spends "4-5 hours" on the phone to arrange for a change in a minor re- quirement. In contrast, she easily negotiates such change with a com- mercial customer. In answering question 7, respondents confirm managers' and coordi- nators' indications: that the writers' degree of involvement in the writing process, the kinds of writing they do, and their project affiliations influence their awareness of the audience. In particular, lead writers have greater awareness of the audience than writers under them, writers of user documentation know the audience better than writers of specifications, and writers in the commercial sphere know the audience better than military software writers. 185 Table 16. Question 7: "In general, how do you write in order to meet customer requirements?" RESPON- DENT METHOD 1 The respondent presents clear ideas by "throwing away the fuzzy parts." 2 Before anything is done, we give the customer a "Statement of Work," which the customer reviews; the customer then tells us whether he accepts our approach. We then do everything according to these stated technical requirements. Structured Analysis might encourage a more understandable Statement of Work and eliminate many meetings. 3 We follow a DID (Data Item Description) submitted by the customer. Data Management from our side and the customer's must work out any ambiguities in the DID. 4 Systems analysts must define the requirements seen in the customer specification, attempting to untangle whatever they do not understand. Analysts may then write a requirements document that takes into account each customer requirement--develop a check list of customer requirements, then write against this list. They must finally review the document piecemeal, making sure that the customer and senior engineers agree at every step. A system verification team independent of Systems Analysis writes a test document describing the testing of all requirements in the customer specification (in this case, Boeing's), then looks for a discrepancy between the customer's understanding of the requirements and the system team's. . (If Systems Analysis tells software to design the system to meet a certain requirement, but Software Verification under- stands this requirement differently, the discrepancy will show up in testing.) The customer specification is never complete--engineers must take license to complete it, and if the customer Objects, the customer must state a new requirement--but an initial walkthrough with the customer should avoid this problem. 186 Table 16 (cont'd.) RESPON- DENT METHOD (cont'd.) The customer writes specifications in narrative text, which is difficult to read and understand, so customer require- ments are difficult to meet--a structured specification from Boeing would solve this problem. ' In the ARN-101 project, the field testing produced "patches" (quick fixes to code done in the field). (People in the field write such patches, and software staff members in Grand Rapids have to fully integrate these patches into the system, revising the code and changing the documentation to reflect these fixes.) The respondent was supposed to write like the person who wrote the patch in the field and to change the field repre- sentative's work as little as possible, but he found it better to rewrite instead of borrowing; and he soon resented the field representative's writing. In this and other situations, the respondent has felt that the push to promptly release revised material to the customer supersedes concern for the customer's needs, in both coding and documentation. Documentation going to the customer should be checked by someone who is good at writing-~someone who is aware that small comments or memos within the code need clarification, someone who has both writing and technical skill, not some- one who thinks that "anything on paper" is good enough. A customer review during the process of writing and validation exercises to test the final written product are the keys. The respondent reads the customer's written statement of requirements, which describes the contents of the planned document paragraph-by-paragraph, and writes the document by using the same paragraph numbers and headings the customer has listed. For a proposal, the respondent follows the customer's Request for Proposal and emphasizes the solutions to the questions the customer raises in the RFP. For an ongoing project, the respondent writes monthly and quarterly reports to the customer to make sure that the project is satisfying the customer's wishes. 187 Table 16 (cont'd.) RESPON- DENT METHOD 10 ll 12 13 14 The respondent starts with the outline the customer provides, the Data Item Description, and translates the customer's statements into his own terminology. He may find that the DID, the Statement of Work, the original proposal for the project, the development plan, the Critical Item Specification, and Military Standards for docu- mentation all conflict. All of these items should agree in reflecting the customer's wishes, but the group of people who comprise the customer do not get together to coordinate their specifications, so the writer must negotiate with the customer representative to find out what the customer really wants. Representatives from LSI/ID must negotiate with the customer to find out what the customer will tolerate in documentation. The terms of the contract may be avoided through negotia- tion. The respondent writes in conformity to the customer's Data Item Description, but this statement is ambiguous, so the respondent tries to define top-level requirements in a vague manner that allows some latitude. To write a proposal, the respondent follows the customer's Statement of Work. The Statement of Work is ambiguous, but the customer clari- fies it in oral conversation. Such conversation develops a relationship with the customer as well as clarifies the SOW. The respondent does not think about the customer: he thinks of a Part I as a document addressed to the internal software department; he thinks of a test procedure as a document for anyone who wants to run the described tests, probably an internal party. The respondent complies with the specification submitted by the customer. For hardware applications, this specification is usually unambiguous. The respondent simply writes in compliance with the same check list the inspector (a customer representative) uses. 188 Table 16 (cont’d.) RESPON- DENT METHOD 15 The respondent finds it easy to negotiate with Boeing to change the requirements for a document--Boeing is a "cohort in crime." In contrast, the respondent has had to talk on the phone for 4-5 hours to change a requirement for a mili- tary document. 189 SUMMARY Respondents' answers to questions 1 through 4 show how their plan- ning activities, writing strategies, and revision techniques express concern to establish audience and purpose. Many writers begin writing, formulate ideas and expressions while writing, and revise by using techniques that encourage a sense of the audience. Writers and lead writers use storyboards and walkthroughs to develop the logical coherence of text, and they often explain or discuss text orally, either to share knowledge with others or to aid their revision of a text. Through these activities, writers and lead writers attempt to better understand the purposes that each text serves. By answering questions 5 and 6, writers and lead writers further show that their writing strategies reflect concern for the purpose and audience. Respondents decide when and how to use a figure or table in text by considering the purpose and audience. Particularly in speci- fications, where a scientific purpose, representation of reality, is primary, respondents employ a figure or table to foster accurate correspondence between the text and the process it describes. In persuasive and informative forms, where the audience is a more central focus, respondents use a figure or table to attract the reader's atten- tion. Respondents evaluate structured methods with concern for saving time and effort, but also for fulfilling the scientific aim of the specification and achieving clear communication with their audience. 190 Respondents' replies to question 7 partially confirm the hypoth- eses derived from the survey of managers and coordinators: that writers' and lead writers' senses of audience reflect their levels of involvement in the writing process, the kinds of writing they do, and their affiliations with projects. Opportunity to work as a lead writer, to write user documentation, or to participate in a commercial project does encourage participants' awareness of the end user, because their level of contact with the customer increases through these activities. 0n the other hand, the survey results in total suggest that most respondents have developed considerable awareness of their purposes and audiences, whatever their Opportunities. Though the context in which they write may work against such awareness, these individuals can over- come environment to achieve it. CONCLUSION In the introduction, this study reviewed commentators from the field of electrical engineering, who described the effects of time con- straints, organizational dilemmas, and difficulties of communication on large-scale software projects in the 19603 through the early 19805. Brooks, DeMarco, Wasserman, and Ross and Schoman all described these complexities Of large-scale software projects. The introduction then posed two questions: First, do the texts that software writers produce at Lear Siegler, Inc./Instrument Division demonstrate unified purposes despite the difficulties facing software developers? Second, despite these difficulties, can writers maintain firm senses of purpose and audience? In chapter 1, this study used the Kinneavyan model to clarify the unified purposes Of software texts at LSI/ID. The proposal, an example of persuasive discourse, first aims to change the perspective of the customer--to make this audience support a proposed project. In con- trast, specifications and test documents, examples of scientific discourse, focus on the reality they describe and make their relevance to the audience secondary. User documents, examples of informative discourse, make reality their primary focus, but also strongly address the informational needs of their audiences. In each case, the logic, organization, and style of the text work together to support the purpose. 191 192 The study then turned to examine writers' concepts of purpose and audience, to identify their audiences, and to describe their tasks in settings like LSI/ID. Chapter 2 showed how contributors to the IEEE Transactions eh Professional Communication have evaluated the engineer- ing writer's senses of purpose and audience, identified the writer's audience, and described the writer's task in the engineering corpora- tion. In 1981-85, these contributors made progress toward clarifying purpose and audience in corporate settings: many showed that engineer- ing writers should cultivate senses of purpose and audience in relation to specific kinds of writing; that these writers address a diverse audience; and that engineering writers should consider awareness of purpose and audience an important component of their tasks. Con- tributors have helped clarify the purposes and audiences of engineering writing, in general, though their explanations of purpose and audience neglect to treat some complexities specific to software writing in large-scale projects. Finally, in chapters 3 and 4, this study surveyed software writing at Lear Siegler, Inc./Instrument Division and discovered several varia- bles that influence writers' awareness of purpose and audience. Writers' and lead writers' levels of involvement in software writing, the kinds of writing they do, and their affiliations with projects all influence this awareness. Chapter 3 demonstrated that 15 managers and coordinators rate writers' senses of purpose and audience low, but chapter 4 showed that 15 writers and lead writers have relatively 193 well-developed senses of purpose and audience. The lead writers and writers surveyed can describe the purposes of the methods they use and can identify their audiences. Chapter 4 showed that software writers at LSI/ID in the mid-19805 have overcome the difficulties that Brooks and others described as common in software projects of the 19608 through the early 19803. But chapter 4 also confirmed the hypothesis developed in chapter 3: that some software writers must work harder than others to cultivate knowledge of purpose and audience. First, writers who are not lead writers must work harder than lead writers. The average writer has less direct contact with the customer and potential internal readers than the lead writer has; therefore, this writer must strive for awareness of who these audiences are and how they use documents. Second, writers of specifications must work harder than writers of user documentation to establish the needs of audiences. Writers of specifi- cations typically have little or no contact with their readership in comparison to writers of user documents, who have direct contact with readers during document test runs. On the other hand, writers of specifications have fairly rigid guidelines to follow as they construct the organization Of the text, and knowledge of the audience is not a primary issue for them. Third, writers in the military sphere must generally work harder than their counterparts in commercial software to establish senses of purpose and audience. Although writers for the military have access to formal resources for knowing the customer's 194 wishes, for instance, Data Item Descriptions, they generally lack the level of informal contact with the customer that writers in the com- mercial sphere achieve. These writers for the military must thus exert more effort than their counterparts in commercial software to know the uses their texts will serve. In sum, despite the continuing complexities of large-scale software projects, software writers at Lear Siegler, Inc./Instrument Division are able to compose texts with unified purposes, to provide convincing rationales for the methods they use, and to identify their readers. However, some kinds of writers know more than others about the purposes and audiences of software writing: lead writers know more than the writers who work under them; writers of user documents know more than writers of specifications; and writers who address a commer- cial customer know more than writers in the military sphere. APPENDIX APPENDIX This study has concluded that software writers at Lear Siegler, Inc./Instrument Division are generally aware of their purposes and audiences, but that some writers have more knowledge of purpose and audience than others. In particular, lead writers know more than the writers they supervise; writers of user documents know more than writers of specifications; and writers who address a commercial customer know more than writers in the military sphere. To promote greater awareness of purpose and audience among those who have less of it, a company like LSI/ID could institute two specific measures. This appendix will sketch the nature of the first measure--a group of editors to manage the processes of software writing--and leave specific details of its implementation to managers. The appendix will describe in more detail the nature of the second measure--a class for software writers--and record its initial implementation and testing. As a first measure toward furthering awareness of purpose and audience among software writers, a company like LSI/ID could make the process of software writing itself a less difficult context for writers' activity by expanding the role of document coordinators, developing a group Of editors to manage this process. In particular, this group would manage the writing of engineering documentation, where, the study has shown, writers demonstrate less awareness of purpose and audience. A group of editors dedicated to coordinating 195 196 writers' senses of purpose and audience would help writers work with a unified purpose to satisfy the multiple audiences of a text. These editors would act as intermediaries between those who had special knowledge of external audiences, usually managers and lead writers, and those writers who might benefit from such knowledge. Editors could advise writers of their responsibility to sense two audiences: an internal audience that emphasizes the organization of software texts around technical content and an external audience that emphasizes organization in conformity to a recognized format. Software writers usually expect the form of a text, including its organization, to directly reflect its technical content: the logic of the computer processes it describes. The external customer expects the form to follow the organization, paragraph-for-paragraph, established in the Data Item Description. Especially in the military sphere, a dedicated group of editors could moderate the sometimes conflicting expectations of these two audiences. These editors could work with software writers; internal parties who represent the customer's interests, like Data Management; and the customer to ensure that the form of a document satisfied both internal and external audiences. As a second measure toward developing awareness of purpose and audience among software writers, a company like LSI/ID could Offer appropriate classroom training. A class for software writers could strengthen their senses of purpose and audience by introducing them to managers Of writers, lead writers, and coordinators Of writers (includ- ing, in the future, members of a software editorial group) who 197 had more opportunity than the average writer to become acquainted with these purposes and audiences. The class could bring writers together with managers of writers, lead writers, and coordinators of writers who were able to share what they had learned about external and internal audiences of software writing and the purposes that texts serve for these audiences. Through interchange with these experts, writers could benefit not only from the second-hand information the experts passed to them, but also from first-hand exchanges with the experts themselves, who would represent the writers’ internal audiences. Such a class should focus on engineering documentation, the area this study has identified as a problem, particularly engineering docu- mentation for the military. Through the two surveys recorded in chapters 3 and 4, this study has uncovered ample evidence that writers of engineering documentation Often have weaker senses of purpose and audience than writers of user documentation and that writers in the military sphere Often have weaker senses of purpose and audience than those who address a commercial customer. While a short class for writers might easily cover writing in both the military and commercial spheres, it could hardly cover the writing of proposals and user documentation in addition to engineering documentation. (Moreover, most writers in companies like LSI/ID compose engineering documenta- tion--a minority prepare proposals and user documentation.) Thus, such a class should focus on the writing of engineering documentation and, while addressing commercial applications also, make military applica- tions its first concern. 198 In winter 1985, as a first step toward organizing such a class for software writers, I asked the 15 writers and lead writers of the second survey what such a class ought to include. Their response, summarized in Table 17, suggested much about the content of a class for software writers, in fact, more than the class could reasonably cover in the ten hours allotted to it; therefore, I reduced their collective responses to those comments that specifically concerned the development of purpose and audience and grouped these comments into the following three divisions. First, two respondents suggested that writers of user documenta- tion and reports should learn to clarify their purposes for the reader: respondent 1, that writers should "avoid too much detail and provide more overview in a user's or systems manual"; and respondent 4, that they should learn "to produce English abstracts," to succinctly encapsulate the purposes of reports. Second, four respondents suggested that writers learn to serve the external and internal audiences Of engineering documentation. Accord- ing to respondent 2, writers should "learn to read and understand [the customer's] requirements"--including the standards for specifications required by the Department of Defense--so they can clearly address the customer's needs. Three other respondents suggested that writers learn to use documents as tools for communication with internal audiences. Respondent 6 instructed that writers should learn to write documents 199 Table 17. Respondents' Suggestions for Content of Class RESPON- DENT SUGGESTIONS 1 Writers must learn to avoid too much detail and provide more overview in a user's or systems manual. Writers should learn to strive for short sentences and the active voice. The class should include many examples. The class should cover the layout of a document: white space, point type, paragraph numbering (not describe standard layout, but present criteria for a good document layout). 2 Writers should learn to intelligently use a modular approach for design in Part II's. They should learn to use as many figures and tables as they can. Writers must learn to read and understand requirements, to find a consistent way to write a specification before they begin. They should become familiar with Military Standards 490 and 483 [the most common military standards for documenta- tion] but learn to use them as guidelines, not the Bible-- to change the requirements of the specification if necessary and present a suitable argument for doing so to the customer. 3 Writers need a checklist/guide of rules for grammar and punctuation and the resource Of a person who can explain them when questions arise. Writers need to know methods of planning and revising--they should learn to go about these activities in an organized way. They need techniques for communication: When to use a figure or table. How to best explain an idea. 4 Writers need to avoid ambiguous language and achieve precision. They need to accomplish brevity and less detail (by sticking to the requirements). They need rigor in following rules, the ability to produce English abstracts, and the skill to introduce a personal element into their writing without sounding unprofessional. 200 Table 17 (cont'd.) RESPON- DENT SUGGESTIONS Writers must take pride in their writing and learn not to be easily satisfied--some do not think or speak clearly, so how can they write clearly? Writers should learn to use outlines, to structure paragraphs, to have a thesis and concluding paragraph, and to use the inductive funnel [the interviewer's paraphrase] to get the reader's interest. Writers should learn to work within time constraints: they must often do the documentation after the system works, do ”coding on the fly," and dispense with Structured Design techniques because there is no time for them ("There's never time to do it right--there's always time to do it over"). Writers should learn to use automation to keep notes: handwritten notes are difficult to decipher two weeks after they are written. Writers need to know who will use documentation and how they will use it. Sit down and wade through? Use as a reference? Writers should learn to pin down all of the requirements before they start: Writers must learn to communicate with the writers Of software and others from whom they need information. They must learn to do documentation concurrently with the production of code. Engineers don't know how to get started--they are concerned with format more than content. They should not ask, "What do I have to include, and where do I have to place it?" but "What is a good format (not necessarily the right one)?" (One engineer did not realize that he had already written a software development plan because it didn't conform to format.) Format is important for the customer--but we don't need it in-house. Let's let people loose so that they can think creatively in a software development plan. 201 Table 17. (cont'd.) RESPON- DENT SUGGESTIONS 7 (cont'd.) Engineers need to develop truly functional documentation. Classically, documentation is a record of what's already done. The true use of documentation is as a communication pathway: it should aid communication between participants in a project. Communication, not the specification, should be the product. Engineers need to know what to do with tools, not how to get more tools. Software tools are not the answer--objectives are. Example: The CSFDR group tried to use the same computer requirements traceability tools used by FMCS, but they found that plain pieces Of paper were better than these tools. Engineers don't understand that all of the following are tools: documents, meetings, reviews, and milestones. Engineers and engineering management should recognize that documents are important tools: Engineers need to recognize the intangible tools as well as the tangible ones--engineering management does not know how to use documents as tools. 95% of successful communication is oral, but complexity demands good written communication. We spend a lot on tools--documents--which we never use. Managers can use documents as tools to measure the quality, not just the accomplishment, of a job. Those at a lower level can use software documents for pacing--to do so, they must develop complete knowledge of the requirements before doing the coding. Management must set up a time frame which allows for quality documents: so much time for writing, so much time for word processing, etc. People are looking for tools to produce documentation faster and easier when the real problem is learning how to use documentation. Management sometimes makes documents nonfunctional by the attitude "They're just something that has to be done." 202 Table 17. (cont'd.) RESPON- DENT SUGGESTIONS 10 ll 12 13 Writers must learn to write more complete comments embedded in code. Some writers have never taken a writing course and need a better understanding of basic communication. They need some work on sentence structure, on express- ing complete thoughts. They need to determine their audience and address this audience. Writers need to know the customer's level: how much the customer can understand. Writers must learn to express themselves concisely, not to throw in extraneous words. If they really understand a problem, they should be able to write about it concisely. They must learn that there are places for humor. A class should make people write, then critique their writ- ing. Many writers develop documents by imitating what others have written previously--but those who have written before may not know what should be in the document any better than the imitator. Writers should know how to organize any piece of writing, how to get a logical flow and use an outline. Writers should use active, transitive verb forms (Andy Rooney is a good model). Writers especially need to know more about grammar and sentence structure. They need to make engineering writing more readable and less dry, to add a flair. They must learn how to structure a report to make it flow. 203 Table 17. (cont'd.) RESPON- DENT SUGGESTIONS 14 15 Writers must learn to get documentation done on time, to do documentation early and send it to Technical Publications so that Tech. Pubs. has time to work with it. Software people need writing specifications: norms to write by. However, the software field is constantly changing and diverse (e.g., the difference between the Flight Management Computer System [a commercial project] and the ARN-lOl project [a military project]), and the government does not know what it wants, so it is hard to establish a norm for writing. The structured approach is good, but it must be taught to "the guy who has never seen it before." Writers must learn that the technical aspects of document content are more important than rules of format. 204 "concurrently with the production of code" to serve the system imple- menters during the course of a project, not just the customer after- ward; and respondent 15, that writers should conform to technical considerations above format guidelines to best serve these implement- ers. Similarly, respondent 7 suggested that writers can learn to use documentation "as a communication pathway" for system implementers during the course of a project, not just a record for the customer at its conclusion. Third, four respondents suggested that writers should learn general skills that serve both external and internal audiences: "in- troduce a personal element into their writing without sounding un- professional" (resp. 4); organize the text so as to solicit the reader's interest (resp. 5); and make the interests and level of audience evident in the text (resp. 6 and 9). The survey results show these writers' and lead writers' recog- nition that the form of a text should serve its purposes and audiences. In general, respondents asserted that writers should learn to stress the main point of their writing and to subordinate detail, i.e., communicate a clear sense of purpose, and to address the external or internal reader's needs, stated or unstated. The class I organized in January 1986 introduced 24 participants to seven support instructors from various departments within the company in five two-hour sessions. The class strongly reflected writers' and lead writers' concerns that the form of a text should suit its purposes and audiences by, first, introducing writers to experts 205 who understood the guidelines governing the form of software texts, and, second, familiarizing software writers with their external and internal audiences. The class established a strong focus on the varied audiences writers address. For instance, in the first two sessions, one manager of writers and one lead writer explained to writers how they may satisfy the purposes of external and internal audiences. Through these support instructors, the class made writers aware of their responsi- bilities to both audiences. The first support instructor--a manager of writers from Data Management--represented for writers the interests of an external audience by emphasizing that the organization and style of engineering documents must conform to the customer's written guidelines. In contrast, another support instructor--a lead writer from Military Systems--represented an internal audience by suggesting that the organization of test documents should reflect the logic Of the testing they describe. These instructors thus represented the concerns Of two different types of reader: external and internal. The Section Manager from Data Management explained to participants how to satisfy the military customer by making the content and organi- zation of a document conform to the Data Item Description (a customer's paragraph-by-paragraph description of a document), as the project con- tract dictates. The Section Manager explained that software writers must adopt the organization and style that the DID prescribes for each document. If, for any reason, a writer needs to deviate from the DID, 206 the writer must obtain a waiver from the customer for each specific deviation. Writers will meet the customer's expressed requirements if they follow the letter of the DID and obtain the customer's approval for any specific deviations from its provisions. In the next segment Of the class, the lead writer from Military Systems explained how to make the organization of test documents serve the technical needs of an internal audience. The lead writer agreed with the Section Manager from Data Management that the organization and style of test documents should follow the DID to satisfy the customer, but he explained that these documents should also address internal parties, like analysts, designers, and programmers, who must modify requirements, design, and coding to reflect the test results. The organization of test documents must serve an audience that needs to understand the implications of passed and failed tests for analysis, design, and coding. While test engineers must compose Test Plans, Procedures, and Reports that conform to DIDs, these engineers must also ensure that the organization Of test documents helps an internal audience understand their implications. Following these two support instructors' presentations, I suggest- ed to class participants that their views were complementary. For the Section Manager from Data Management, the chief audience is external: the customer who, after the fact of actual design and testing, wishes to verify that LSI/ID has carefully derived the design of a software system from his requirements and tested the design to make certain 207 that it meets these requirements. The Section Manager from Data Management would have writers serve this external audience by document- ing system design and testing in an established, very familiar format. In contrast, the lead writer from Military Systems would have writers address an internal audience of engineers who wish to use documents while they are designing and testing a system, not after the fact, so they can constantly modify system design to reflect the results of testing. The lead writer would have writers serve this audience by composing internal documents free from the constraints of an estab- lished format. The lead writer agreed with the Section Manager that a document should follow the exact organization the customer stipulates, but suggested that internal audiences may benefit from additional docu- ments without the customer's organizational requirements. Through this pair of presentations, the software writers who participated in the class gained a valuable illustration of how the form of a text becomes a function of purpose and audience. These writers saw how the details Of document organization are part of its orientation to audience-~internal or external--and that they must subordinate their decisions about document organization to concerns for external and internal audiences. First, writers must make the organi- zation serve the customer by carefully following the outline the DID requires. Second, where possible, writers may serve an internal audience in portions of formal documents or in whole informal documents, with an organization that serves technical concerns by 208 emphasizing the relationships between system requirements, design, coding, and testing. The response of class participants to the support instructors' presentations proved positive. According to evaluation forms that sixteen participants completed following the class, fourteen believed that presentations were practical while two believed that these pre- sentations were only somewhat practical. These presentations achieved this measure of success because they addressed the needs that writers and lead writers had identified in the second survey. Though support instructors represented different audiences, all encouraged the writers who attended to emphasize the overall organization of a text, to subordinate detail to this organization, and to make this organization a function of the external or internal reader's purposes, stated or unstated. This appendix has suggested two ways Lear Siegler, Inc./Instrument Division and similar companies may promote stronger senses of purpose and audience among software writers. The appendix has outlined the first, a group of editors to manage this process, in the barest detail. Corporate management can best determine the exact implementation of this first proposal and the composition of such a group, a matter outside the purview of this study. This appendix has also described a second proposal, a class for software writers. The support instruc- tors' presentations in a trial implementation of such a class have familiarized writers with their external and internal audiences and 209 instructed them to subordinate the organization of texts to the purposes of these audiences. According to participants' evaluations, these support instructors' presentations have proven "practical." In these two ways, Lear Siegler, Inc./Instrument Division and similar companies can reinforce and strengthen software writers' already well-developed senses of purpose and audience. LIST OF WORKS CITED LIST OF WORKS CITED Abshire, Gary M., and Dan Culberson. "A Team Approach to Producing Good Documentation." IEEE Transactions eh Professional Communica- tion. 28, 4 (December 1985): 38-41. Alred, Gerald, J. Review of Technically--Write!, 2nd ed., by R. S. Blicq (Englewood Cliffs, NJ: Prentice-Hall, 1981). IEEE Transac- tions eh Professional Communication. 26, 1 (March 1983): 42-43. Andersen, Dan. "Getting Engineers to Write." IEEE Transactions eh Professional Communication. 26, 4 (December 1983): 170-71. Anderson, Paul V. "What Technical and Scientific Communicators Do: A Comprehensive Model for Developing Academic Programs." IEEE Transactions eh Professional Communication. 27, 3 (September 1984): 161-67. Andrews, Alex M. "Technical Writing: The Engineer's Masterpiece." IEEE Transactions eh Professional Communication. 24, 3 (September 1981): 141-45. Arms, Valerie M. "Engineers Like to Write--On a Computer." IEEE Transactions eh Professional Communication. 26, 4 (December 1983): 175-77. Arnold, William R. "Vehicles for Documentation." IEEE Transactions eh Professional Communication. 27, 4 (December 1984): 222-29. Atlas, Marshall A. "The User Edit: Making Manuals Easier to Use." IEEE Transactions eh Professional Communication. 24, 1 (March 1981): 28-29. Baggett, Patricia. "Four Principles for Designing Instructions." IEEE Transactions eh Professional Communication. 26, 3 (September 1983): 99-105. Bahill, A. Terry. "Write for the Reading System; Talk to the Listening System." IEEE Transactions eh Professional Communication. 28, 2 (June 1985): 44-45. Bailey, M. C., and W. Pferd. "Graphics-Based Instruction for Inter- active-Graphics-System Training." IEEE Transactions eh Profes- sional Communication. 25, 2 (June 1982): 67-73. 210 211 Baird, John E., Jr. "How to Overcome Errors in Public Speaking." IEEE Transactions eh Professional Communication. 24, 2 (June 1981): 94-98. Barnum, Carol M. "Teaching Technical Writing to the Engineering Student." IEEE Transactions eh Professional Communication. 25, 3 (September 1982): 136-39. Barry, Jeanne G. "Computerized Readability Levels." IEEE Trans- actions eh Professional Communication. 24, 1 (March 1981): 45-46. Bates, Gary D. "Upgrading Written Communication--Your Firm's and Your Own." IEEE Transactions eh Professional Communication. 27, 2 (June 1984): 89-92. Beck, Charles E. "Conducting an Editing Workshop." IEEE Transactions eh Professional Communication. 28, 1 (March 1985): 43-45. Beck, Charles E. Review of Creating the Technical Report, by Steven Schmidt (Englewood Cliffs, NJ: Prentice-Hall, 1983). IEEE Transactions eh Professional Communication. 27, 1 (March 1984): 49. Beck, Clark E. "Proposals: Write to Win." IEEE Transactions eh Professional Communication. 26, 2 (June 1983): 56-57. Beck, Clark E. Review of Preparing Contract-Winning Proposals and Feasability Studies, by Tim Whalen (New York: Pilot, 1982). IEEE Transactions eh Professional Communication. 27, 4 (December 1984): 230. Benrey, Ronald M. "Top-Down Management Communication: The View from Mid-Channel." IEEE Transactions eh Professional Communication. 28, 3 (September 1985): 17-20. Berry, Elizabeth. "How to Get Users to Follow Procedures." IEEE Transactions eh Professional Communication. 25, 1 (March 1982): 22-25. Booher, E. Kathleen, and Wilma Davidson. "Eleven Myths About Writing-- And How Trainers Can Debunk Them." IEEE Transactions eh Ete- fessional Communication. 25, 3 (September 1982): 133-35. Bostian, Frieda R. "Technical Writing--'Very Useful Stuff.'" IEEE Transactions eh Professional Communication. 27, 3 (September 1984): 121-25. 212 Braby, R., and others. "Illustrated Formats to Teach Procedures." IEEE Transactions eh Professional Communication. 25, 2 (June 1982): 61-66. Bradford, David. "The Personal in Microcomputer Documentation." IEEE Transactions eh Professional Communication. 27, 2 (June 1984): 65-68. Brockmann, John R. Review of How to Write Computer Manuals for Users, by Susan J. Grimm (Belmont, CA: Lifetime Learning, 1982). IEEE Transactions eh Professional Communication. 26,1 (March 1983): 45-46. Brockmann, R. John. Review of A Method for Designing Comphter Support Documentation, by Richard E. Beard and Peter V. Callamaras (Master' 8 Thesis," LSSR 54- -83 USAF, 1983). IEEE Transactions eh Professional Communication. 27, 2 (June 1984): 108-109. Brockmann, R. John. Review of Documentation Development Methodology, by Sandra Pakin and Associates (Chicago: Sandra Pakin, 1982). IEEE Transactions eh Professional Communication. 26, 1 (March 1983): 45-46. Brockmann, R. John. Review of Handbook Lf Screen Format Design, by Wilbert O. Galitz (Wellesley, MA: Q. E. D. Information Services, 1982). IEEE Transactions eh Professional Communication. 27,4 (December 1984): 232. Brockmann, R. John. Review of The DP Professional' 3 Guide to Writing Effective Technical Communication, by J. Van Duyn (New— York: Wiley-Interscience, 1982). IEEE Transactions eh Professional Communication. 26, 1 (March 1983): 45-46. Brockmann, R. John. Review of Writing Handbook for Computer Pro- fessionals, by William D. Skees (Belmont, CA: Lifetime Learning, 1982). IEEE Transactions eh Professional Communication. 26, 1 (March 1983): 45. Bronson, Judith Gunn. Review of Business and Technical Writing Cook- book. How to Write Coherently Ln the Job, by T. M. Georges (Boulder, CO: Syntax, 1983). IEEE Transactions Ln Professional Communication. 26,2 (June 1983): 90. Bronson, Judith Gunn. Review of Successful Writing at Work, by Philip C. Kolin (Lexington, MA: Heath, 1982). IEEE Transactions Ln Professional Communication. 27, 1 (March 1984): 49. Brooks, Frederick P., Jr. The Mythical Man-Month: Essays eh Software Engineering. Reading, MA: Addison-Wesley, 1975. 213 Bruce, Bertram, Andree Rubin, and Kathleen Starr. "Why Readability Formulas Fail." IEEE Transactions on Professional Communication. 24, 1 (March 1981): 50-52. Burchard, Gina M. "Courseware Design: New Roles for Text and Technical Writers." IEEE Transactions on Professional Communication. 28, 1 (March 1985): 20-26. Burchard, Gina M. "Professional Accountability in the Senior Engineer- ing Lab." IEEE Transactions on Professional Communication. 27, 2 (June 1984): 93-96. Burke, Thomas E. "You'll Never Get Ahead in Engineering If You Can't Make Yourself Understood." IEEE Transactions 92 Professional Communication. 27, 1 (March 1984): 25-28. Casari, Laura E. "Required: Three Hours in Technical Communication-- Paradigm for a Paradox." IEEE Transactions on Professional Communication. 27, 3 (September 1984): 116-120. Chaffee, Patricia. Review of Personal Documentation for Professionals, by Vladimir Stibic (New York: North-Holland, 1980). IEEE Trans- actions 93 Professional Communication. 24, 2 (June 1981): 106-07. Coney, Mary B., and Judith A. Ramey. "A Communication Curriculum in Engineering Education: An Alternative Model.” IEEE Transactions on Professional Communication. 27, 3 (September 1984): 138-43. Corey, Jim. "Lead Your ACE: Accuracy, Clarity, and Effectiveness in Technical Writing." IEEE Transactions on Professional Communi- cation. 26, 1 (March 1983): 13-14. Cosgrave, M. C. "Writing for 'The Audience.'" IEEE Transactions on Professional Communication. 27, 1 (March 1984): 38-41. Crandall, Kathleen Eilers. "Writing for Adult English Language Learners." IEEE Transactions on Professional Communication. 28, 4 (December 1985): 3-10. Crane, Dave. "Writing for Closed-Captioned Television for the Hearing- Impaired." IEEE Transactions on Professional Communication. 28, 4 (December 1985): 15-18. Crawford, C. C. "How to Gather and Organize Ideas Quickly." IEEE Transactions 92 Professional Communication.< 26, 4 (December 1983): 187-90. 214 Daley, Kevin R. "Presenting Your VieWpoint." IEEE Transactions 93 Professional Communication. 24, 2 (June 1981): 91-94. Davis, Richard M. "Publication in Professional Journals: A Survey of Editors." IEEE Transactions on Professional Communication. 28, 2 (June 1985): 34-43. DeMarco, Tom. Structured Analysis and System Specification. New York: Yourdon, 1978. DeMare, George. "Communicating at the Top." IEEE Transactions on Professional Communication. 24, 2 (June 1981): 99-101. Denton, L. W. Review of An Introduction £9 Technical Publishing, by Anthony H. Firman (Pembroke, MA: Firman, 1983). IEEE Trans- actions on Professional Communication. 27, 2 (June 1984): 109. Denton, L. W. Review of Communication Training and Consulting in Business, Industry, and Government, ed. William J. Buchholz (Urbana, IL: American Business Communication, 1983). IEEE Transactions on Professional Communication. 27, 1 (March 1984): 47-48. Denton, L. W. Review of Layout: The Design pg the Printed Page, by Allen Hurlburt (New York: Watson-Guptil, 1977). IEEE Trans- actions 99 Professional Communication. 26, 4 (December 1983): 213. Denton, L. W. Review of The Technology 9: Text: Principles for Structuring, Designing and Displaying Text, David H. Jonassen, ed. (Englewood Cliffs, NJ: Educational Technology Publications, 1982). IEEE Transactions on Professional Communication. 26, 1 (March 1983): 44-45. Devet, Bonnie. Review of Write go the Point: Effective Communication in the Workplace, by Michael B. Goodman (Englewood Cliffs, NJ: Prentice-Hall, 1984). IEEE Transactions gn Professional Communi- cation. 28, 1 (March 1985): 53-54. Diehl, William, and Larry Mikulecky. "Making Written Information Fit Workers' Purposes." IEEE Transactions on Professional Communi- cation. 24, 1 (March 1981): 5-9. Dobrin, David. "Do Not Grind Armadillo Armor in this Mill." IEEE Transactions on Professional Communication. 28, 4 (December 1985): 30-37. Dressel, Susan. "Generating a Quick First Draft." IEEE Transactions on Professional Communication. 26, 4 (December 1983): 172-74. 215 Drury, Alinda. "Evaluating Readability." IEEE Transactions 92 Professional Communication. 28, 4 (December 1985): 11-14. Dunkle, Susan B., and Purvis M. Jackson. "Structuring: Relating Old and New Knowledge." IEEE Transactions 93 Professional Communica- tion. 25, 4 (December 1982): 175-77. Echols, Carla, and Lois Pryor. "A Scorecard for Technical Writing." IEEE Transactions 23 Professional Communication. 26, 4 (December 1983): 162-65. Feinberg, Susan, and Jerry I. Goldman. "Technical Writing Attitude Measurement and Instructional Goals." IEEE Transactions 93 Professional Communication. 27, 3 (September 1984): 155-60. Filley, Richard D. "Opening the Door to Communication Through Graph- ics." IEEE Transactions on Professional Communication. 25, 2 (June 1982): 91-94. Flaherty, Deborah L. "The Olympic Experience." IEEE Transactions 9n Professional Communication. 28, 2 (June 1985): 21-23. Fleischhauer, F. William. "Technical Writing in the Management-Systems World." IEEE Transactions 92 Professional Communication. 28, 3 (September 1985): 31-33. Frase, Lawrence T. "Ethics of Imperfect Measures." IEEE Transactions pg Professional Communication. 24, 1 (March 1981): 48-50. Frye, Robert H. "Artistic Technical Training." IEEE Transactions op Professional Communication. 24, 2 (June 1981): 86-89. George, James E., and Anders Vinberg. "The Display of Engineering and Scientific Data." IEEE Transactions 9g Professional Communica- tion. 25, 2 (June 1982): 95-97. Georges, T. M. "Fifteen Questions to Help You Write Winning Pro- posals." IEEE Transactions 93 Professional Communication. 26, 2 (June 1983): 84. Georgopoulos, Chris J., and Voula C. Georgopoulos. "From University Term Papers to Industry Technical Reports--An Attempt to Bridge the Existing Gap." IEEE Transactions 93 Professional Communica- tion. 27, 3 (September 1984): 144-48. Gibson, Jane Whitney, and Richard M. Hodgetts. "Self-Disclosure: A Neglected Management Skill." IEEE Transactions 92 Professional Communication. 28, 3 (September 1985): 41-45. 216 Gleason, James P. "Humor Can Improve Your Technical Presentations." IEEE Transactions 9n Professional Communication. 25, 2 (June 1982): 86-90. Gleason, James P., and Joan P. Wackerman. "Manual Dexterity--What Makes Instruction Manuals Usable." IEEE Transactions 92 Egg- fessional Communication. 27, 2 (June 1984): 59-61. Goldfarb, Stephen M. "Writing Policies and Procedures Manuals." IEEE Transactions 92 Professional Communication. 25, 1 (March 1982): 14-15. Greenly, Robert B. "Technical Writing and Illustrating Strategies for Winning Government Contracts." IEEE Transactions 93 Professional Communication. 28, 2 (June 1985): 7-12. Grice, R. A. "'Cut and Paste' Enters the Computer Age." IEEE Trans- actions 92 Professional Communication. 27, 2 (June 1984): 78-81. Grimm, Susan J. "EDP User Documentation: The Missing Link." IEEE Transactions 92 Professional Communication. 24, 2 (June 1981): 79-83. Gupta, Ashis. "Profiling: A Functional Aid To Effective Communica- tion." IEEE Transactions on Professional Communication. 26, 4 (December 1983): 197-200. _ Gwiasda, Karl E. "Of Classrooms and Contexts: Teaching Engineers to Write Wrong." IEEE Transactions 92 Professional Communication. 27, 3 (September 1984): 149-51. Hackos, Joann T. "Teaching Problem-Solving Strategies in the Technical Communication Classroom." IEEE Transactions pg Professional Communication. 27, 4 (December 1984): 180-84. Hackos, Joann T. "Using Systems Analysis Techniques in the Development of Standards and Procedures." IEEE Transactions op Professional Communication. 28, 3 (September 1985): 25-30. Haness, Joel. "How to Critique a Document." IEEE Transactions pp Professional Communication. 26, 1 (March 1983): 15-17. Hartley, James. "Eighty Ways of Improving Instructional Text." IEEE Transactions 9n Professional Communication. 24, 1 (March 1981): 17-27. Hartley, James. "The Role of Colleagues and Text-Editing Programs in Improving Text." IEEE Transactions 93 Professional Communica- tion. 27, 1 (March 1984): 42-44. 217 Hatley, Derek. Using and Understanding LSI Real-Time Structured Requirements Specifications. Grand Rapids, MI: Lear Siegler, Inc./Instrument Division, 1984. Hays, Robert. "Prescriptions for Using Boilerplate." IEEE Trans- actions 93 Professional Communication. 26, 2 (June 1983): 60-62. Hill, James W. "Bibliography on Management Communications." IEEE Transactions 9n Professional Communication. 28, 3 (September 1985): 47-48. Hodgkinson, Richard, and John Hughes. "Developing Wordless Instruc- tions: A Case History." IEEE Transactions pg Professional Communication. 25, 2 (June 1982): 74-79. Hoffman, John. Review of Audience Analysis and Response, by Patricia Caernarven-Smith (Pembroke, MA: Firman, 1983). IEEE Transactions 22 Professional Communication. 27, 4 (December 1984): 233-34. Horn, William Dennis. "Computer Assisted Writing Instruction at Clarkson University." IEEE Transactions 93 Professional Communi- cation. 27, 4 (December 1984): 197-200. Houze, William C. "The Electronic Imperative: Process Information Intelligently or Perish." IEEE Transactions 92 Professional Communication. 26, 1 (March 1983): 38-41. Howard, Lionel A., Jr. "A Survey of Technical Communication Programs in U.S. Colleges and Universities--1984." IEEE Transactions 9g Professional Communication. 27, 3 (September 1984): 172-76. Huber, Carol E. "The Logical Art of Writing Useful Comparisons." IEEE Transactions 93 Professional Communication. 28, 1 (March 1985): 27-28. Ibrahim, A. M. "What's in an Arabic Name?" IEEE Transactions 93 Professional Communication. 28, 4 (December 1985): 28-29. Jamerson, Frank E. "Communication in Industrial Research Laborato- ries." IEEE Transactions 92 Professional Communication. 27, 1 (March 1984): 35-37. Joenk, R. J. "Encouraging Technical Documentation." IEEE Trans- actions 22 Professional Communication. 26, 4 (December 1983): 158-59. Joenk, R. J. "Preface." IEEE Transactions pg Professional Communica- tion. 25, 2 (June 1982): 58-60. 218 Joseph, Albert. ”Writing Training Materials That Turn People On." IEEE Transactions 93 Professional Communication. 24, 4 (December 1981): 169-71. Kantrowitz, B. Michael. "What Price Technical Editing?" IEEE Trans- actions 93 Professional Communication. 28, 1 (March 1985): 13-19. Katter, O. E., Jr. Review of The Visual Display 9f Quantitative Information, by Edward R. Tufte (Cheshire, CT: Graphic Press, 1983). IEEE Transactions 93 Professional Communication. 27, 2 (June 1984): 108. Keyser, George F., and Eugene M. DeLoatch. "Learning Through Writing in an Engineering Course." IEEE Transactions 93 Professional Communication. 27, 3 (September 1984): 126-29. Killingsworth, M. Jimmie. "A Bibliography on Proposal Writing." IEEE Transactions en Professional Communication. 26, 2 (June 1983): 79-83. Kincaid, J. Peter, James A. Aagard, John W. O'Hara, and Larry K. Cottrell. "Computer Readability Editing System." IEEE Trans- actions 93 Professional Communication. 24, 1 (March 1981): 38-41. Kinneavy, James L. A Theory 9f Discourse. New York: Norton, 1980. Knapp, Joan. "Can Engineers Write?" IEEE Transactions 99 Profession- al Communication. 27, 1 (March 1984): 10-13. Krowne, C. M., and D. H. Covington. "Integrating Engineering and Technical Communications in Sophomore Electrical Engineering Projects." IEEE Transactions 9g Professional Communication. 24, 3 (September 1981): 145-47. Lacy, Ed. Review of Dictionary 9f Computers, Data Processing, and Telecommunications, by Jerry M. Rosenberg (New York: Wiley, 1984). IEEE Transactions on Professional Communication. 27, 4 (December 1984): 231-32. Lear Siegler, Inc./Instrument Division. Software Design Specification for the Flight Management Computer System. Grand Rapids, MI: LSI/ID, 1985. Lear Siegler, Inc./Instrument Division. Structured Design: Basic Concepts pf Structured Desigg. Grand Rapids, MI: LSI/ID. Lear Siegler, Inc./Instrument Division. System Verification Test Plan for the Alternate Navigation Control/Display Unit, draft copy. Grand Rapids, MI: LSI/ID, 1985. 219 Lear Siegler, Inc./Instrument Division. System Verification Test Procedure fee hhe Alternate Navigation Control/Display Unit, draft copy. Grand Rapids, MI: LSI/ID, 1985. Lear Siegler, Inc./Instrument Division. FMCS BITE Pocket Guide EEE 737-300. Grand Rapids, MI: LSI/ID. Lear Siegler, Inc./Instrument Division. Advanced Graphics Avionics Display System (AGADS) Proposal he hhe Avionics Laboratory (AAAT-l) hf AFWAL. Grand Rapids, MI: LSI/ID, 1984. Lear Siegler, Inc./Instrument Division. System/Software Requirements Document for hhe Flight Management Computer System. Grand Rapids, MI: LSI/ID, 1984. Lear Siegler, Inc./Instrument Division. Software Design Specification £95 Ehe Navigation Data Base, rev. Grand Rapids, MI: LSI/ID, 1985. Ledbetter, William N. Review of The Crawford Slip Method, by C. C. Crawford (Los Angeles: U of Southern California School of Public Administration, 1983). IEEE Transactions eh Professional Communi- cation. 27, 2 (June 1984): 109-10. LoMaglio, Larry J., and Victoria J. Robinson. "The Impact of the Passive Voice on Reading Comprehension." IEEE Transactions eh Professional Communication. 28, 4 (December 1985): 26-27. Lopinto, Lidia. "Designing and Writing Operating Manuals." IEEE Transactions eh Professional Communication. 27, 1 (March 1984): 29-31. Losey, Cheryl L. "Electronic Messaging Systems for More Effective Management." IEEE Transactions eh Professional Communication. 28, 3 (September 1985): 35-39. Lutz, Jean A. "A Study of Revising and Editing at the Terminal." IEEE Transactions eh Professional Communication. 27, 2 (June 1984): 73-77. Lynch, Gary. "Documenting Engineering Instrumentation Projects." IEEE Transactions eh Professional Communication. 26, 4 (December 1983): 178-83. MacGregor, A. Jean. "Selecting the Appropriate Chart." IEEE Trans- _————— actions eh Professional Communication. 25, 2 (June 1982): 102-04. Malcolm, Andrew. "How Closed Captions Work." IEEE Transactions eh Professional Communication. 28, 4 (December 1985): 19-20. 220 Malcolm, Andrew. "Introduction." IEEE Transactions eh Professional Communication. 28, 4 (December 1985): 1-2. Mann, James A., and John B. Ketchum. "Multi-Use: Reshaping Technical Material." IEEE Transactions eh Professional Communication. 27, 2 (June 1984): 85-88. Marcus, Aaron. "Designing the Face of an Interface." IEEE Trans- actions eh Professional Communication. 25, 3 (September 1982): 122-26. Marcus, Stephen, and Sheridan Blau. "Not Seeing Is Relieving: Invisi- ble Writing With Computers." IEEE Transactions eh Professional Communication. 27, 2 (June 1984): 69-72. Marcus, Stephen. "The Host in the Machine: Decorum in Computers Who Speak." IEEE Transactions eh Professional Communication. 28, 2 (June 1985): 29-33. Martin, Peter. "Ergonomics in Technical Communication." IEEE Trans- actions eh Professional Communication. 27, 2 (June 19843: 62-64. Mashburn, John, and Janice Vantrease. "Planning a Company Program for Technical Documentation." IEEE Transactions eh Professional Communication. 26, 4 (December 1983): 166-69. Masse, Roger E. "Theory and Practice of Editing Processes in Technical Communication." IEEE Transactions eh Professional Communication. 28, 1 (March 1985): 34-42. Masse, Roger E. "Theory and Practice of Writing Processes for Techni- cal Writers." IEEE Transactions eh Professional Communication. 27, 4 (December 1984): 185-92. Maynard, John. "A User-Driven Approach to Better User Manuals." IEEE Transactions eh Professional Communication. 25, 1 (March 1982): 16-19. McAlister, James. "Build Your Case to Management." IEEE Transactions eh Professional Communication. 28, 3 (September 1985): 21-24. Michaelson, Herbert B. Review of Basic Technical Writing, 5th ed., by Herman M. Weisman (Columbus, OH: Merrill, 1985). IEEE Trans- actions eh Professional Communication. 28, 2 (June 1985): 46. Michaelson, Herbert B. Review of The Technical Communicator's Hand- book ef Technology Transfer, by Hyman Olken (Livermore, CA: Olken, 1980). IEEE Transactions eh Professional Communication. 24, 2 (June 1981): 106. 221 Michaelson, Herbert B. "Teaching Engineering Students to Communicate." IEEE Transactions eh Professional Communication. 27, 3 (September 1984): 152-55. Moffett, John B., Stephen G. Smith, and S. J. DeAmicis. "Technical Brochure Preparation." IEEE Transactions eh Professional Communi- cation. 28, 2 (June 1985): 17-20. Montalbo, Thomas. "Say It in Threes." IEEE Transactions eh EEE' fessional Communication. 24, 3 (September 1981): 128-29. Montoya, Sarah. "Word Watching: Single or Double Consonant." IEEE Transactions eh Professional Communication. 24, 4 (December 1981): 199-201. Montoya, Sarah. "Word Watching: Who or Whom?" IEEE Transactions eh Professional Communication. 24, 2 (January 1981): 84-85. Moorehead, Alice E. "The Conference Approach to Engineers’ Report Writing." IEEE Transactions eh Professional Communication. 28, 3 (September 1985): 13-16. Muenier, Roger H. Review of Style and Readability ih Technical Writing, by James DeGeorge, Gary 0. Olson, and Richard Ray (New York: Random House, 1984). IEEE Transactions eh Professional Communication. 27, 4 (December 1984): 233. Nailen, Richard L. "An Engineer's Guide to Clear Language." IEEE Transactions eh Professional Communication. 24, 3 (September 1981): 117-19. National Council of Teachers of English. "Essentials of English." IEEE Transactions eh Professional Communication. 27, 2 (June 1984): 105-107. Norman, Rose. Review of The Engineer’s Guide he Better Communication, by Richard Arthur (Glenview, IL: Scott Foresman, 1984). IEEE Transactions eh Professional Communication. 28, 1 (March 1985): 54-55. Page-Jones, Meilir. The Practical Guide he Structured Systems Design. New York: Yourdon, 1980. Pakin, Sandra. "Evaluate User Documentation Before You Buy the Software." IEEE Transactions eh Professional Communication. 24, 2 (June 1981): 75-78. 222 Piccoli, Angelina. Review of Designing Usable Texts, by Thomas M. Duffy and Robert Waller (Orlando: Academic Press, 1985). IEEE Transactions eh Professional Communication. 28, 4 (December 1985): 47-48. Pilditch, James. "Did You Read the Instructions Carefully?" IEEE Transactions eh Professional Communication. 24, 4 (December 1981): 185-86. Plung, Daniel L. "Add Style to Your Technical Writing." IEEE Trans- actions eh Professional Communication. 27, 1 (March 1984): 20-24. Plung, Daniel L. ”Readability Formulas and Technical Communication." IEEE Transactions eh Professional Communication. 24, 1 (March 1981): 52-54. Potvin, Janet H. "Using Team Reporting Projects to Teach Concepts of Audience and Written, Oral, and Interpersonal Communication Skills." IEEE Transactions eh Professional Communication. 27, 3 (September 1984): 130-37. Powell, Kenneth B. "Readability Formulas: Used or Abused?" IEEE Transactions eh Professional Communication. 24, 1 (March 1981): 43-45. Powell, Kenneth B. Review of Effective Technical Communication, by Anne Eisenberg (New York: McGraw-Hill, 1982). IEEE Transactions eh Professional Communication. 25, 3 (September 1982): 163. Powell, Kenneth B. Review of The Writing System for Scientists and Engineers, by Edmond H. Weiss (Englewood Cliffs, NJ: Prentice- Hall, 1981). IEEE Transactions eh Professional Communication. 25, 1 (March 1982): 51. Powell, Kenneth B. "Writing with Verve." IEEE Transactions eh Professional Communication. 25, 4 (December 1982): 189-91. "The Process Model of Design." IEEE Transactions eh Professional Communication, reprint from Simply Stated 1 (July 1981). 24, 4 (December 1981): 176-78. Power, Ruth M. "Who Needs a Technical Editor?" IEEE Transactions eh Professional Communication. 24, 3 (September 1981): 139-40. Rathjens, Dietrich. "The Seven Components of Clarity in Technical Writing." IEEE Transactions eh Professional Communication. 28, 4 (December 1985): 42-46. 223 Redish, Janice C. "Understanding the Limitations of Readability Formulas." IEEE Transactions eh Professional Communication. 24, 1 (March 1981): 46-48. Reep, Diane C. Review of Technical and Business Communication ih Two-Year Programs, ed. W. Keats Sparrow and Nell Ann Pickett (Urbana: NCTE, 1983). IEEE Transactions eh Professional Communi- cation. 27, 1 (March 1984): 46. Rivers, William. Review of Style: Ten Lessons ih Clarity and Grace, by Joseph M. Williams (Glenview, IL: Scott Foresman, 1981). IEEE Transactions eh Professional Communication. 26, 2 (June 19831: 88-89. Rogers, Cynthia H. Review of Technical Writing: A Guide with Models, by Bonnie Carter Brinegar and Craig Barnwell Skates (Glenview, IL: Scott Foresman, 1983). IEEE Transactions eh Professional Communication. 28, 1 (March 1985): 52-53. Romm, Ethel Grodzins. "Writing Guide." IEEE Transactions eh EEQ’ fessional Communication. 24, 3 (September 1981): 120-21. Rosenburg, Ronald C. "The Engineering Presentation--Some Ideas on How to Approach and Present It." IEEE Transactions eh Professional Communication. 26, 4 (December 1983): 191-93. Ross, Douglas T., and Kenneth E. Schoman, Jr. "Structured Analysis for Requirements Definition." Software Design Techniques. 4th ed. Ed. Peter Freeman and Anthony I. Wasserman. Silver Spring, MD: IEEE Computer Society Press, 1983. Royal Bank of Canada. "The Practical Writer." IEEE Transactions eh Professional Communication. 24, 2 (June 1981): 63-65. Saunders, Arlan. "Writing Effective Assembly Procedures." IEEE Transactions eh Professional Communication. 25, 1 (March 1982): 20-21. Schiff, Peter M. "Speech: Another Facet of Technical Communication." IEEE Transactions eh Professional Communication. 24, 2 (June 1981): 89-90. Schoenfeld, Robert. "When to Make Nouns Go into Action." IEEE Transactions eh Professional Communication. 24, 3 (September 1981): 123. Seisler, Jeffrey M. "Proposal Writing: Approaching the Approach." IEEE Transactions eh Professional Communication. 26, 2 (June 1983): 58-60. 224 Sharma, B. C. "Graphic Evaluation of Readability Scores." IEEE Transactions eh Professional Communication. 25, 1 (March 1982): 34-35. Skolnik, Herman. "Communicating Technical Information." IEEE Trans- actions eh Professional Communication. 24, 2 (June 1981): 72. Smith, Frank. "Myths of Writing." IEEE Transactions eh Professional Communication. 27, 2 (June 1984): 101-04. Smith, Herb. "Methods for Training the Technical Editor." IEEE Transactions eh Professional Communication. 28, 1 (March 1985): 46-50. Souther, James W. "Identifying the Informational Needs of Readers: A Management Responsibility." IEEE Transactions eh Professional Communication. 28, 3 (September 1985): 9-12. Souther, James W. "What to Report." IEEE Transactions eh Profession- al Communication. 28, 3 (September 1985): 5-8. St. John, Mary. "The Teradata Document Template: A Planning Tool." IEEE Transactions eh Professional Communication. 28, 1 (March 1985): 29-33. Stone, James H. Review of The New Television Technologies, by Lynne S. Gross (Dubuque, IA: Brown, 1983). IEEE Transactions eh BEE" fessional Communication. 28, 1 (March 1985): 52. Strong, David. Review of Pocketbook for Technical and Professional Writers, by Earl G. Bingham (Belmont, CA: Wadsworth, 1982). IEEE Transactions eh Professional Communication. 27, 4 (December 1984): 232. Strong, David. Review of Technology Considerations for the Technical Writer, by R. M. Field (Washington, DC: Society for Technical Communication, 1983). IEEE Transactions eh Professional Communi- cation. 28, 1 (March 1985): 51-52. Strong, David. Review of Writing for Industry: Ah Instruction Manual, by Anita J. Lehman (New York: Holt, 1984). IEEE Transactions eh Professional Communication. 27, 4 (December 1984): 232. Szoka, Kathryn. "A Guide to Choosing the Right Chart Type." IEEE Transactions eh Professional Communication. 25, 2 (June 1982): 98-101. 225 Tibbetts, Arn. "Ten Rules for Writing Readably." IEEE Transactions eh Professional Communication. 25, 1 (March 1982): 10-13. Tredennick, Nick, and Brion N. Shimamoto. "On Systematic Generation of Scientific Papers." IEEE Transactions eh Professional Communica- tion. 24, 3 (September 1981): 124-27. Ulrich, Gail D. "Write a Good Technical Report." IEEE Transactions eh Professional Communication. 27, 1 (March 1984): 14-19. Waller, Robert, Paul Lefrere, and Michael Macdonald-Ross. "Do You Need that Second Color?" IEEE Transactions eh Professional Communica- tion. 25, 2 (June 1982): 80-85. Walter, Gerard G. "Estimating the Vocabulary Size of the Disadvantaged Reader." IEEE Transactions eh Professional Communication. 28, 4 (December 1985): 21-25. Wasserman, Anthony. "Information System Design Methodology." Soft- ware Design Techniques, 4th ed. Ed. Peter Freeman and Anthony I. Wasserman. Silver Spring, MD: IEEE Computer Society Press, 1983. Weaver, Diane Gilman. "Technical Communications for Computer Users." IEEE Transactions eh Professional Communication. 28, 2 (June 1985): 24-28. Whalen, Tim. "Developing an In-House Business and Technical Writing Course." IEEE Transactions eh Professional Communication. 26, 4 (December 1983): 160-61. Whalen, Tim. "Renewal: Writing the Incumbent Proposal." IEEE Trans- actions eh Professional Communication. 28, 2 (June 1985): 13-16. Whittaker, Della A. Review of Guidelines for Document Designers, by Daniel B. Felker, and others (Washington, DC: American Institutes for Research, 1981). IEEE Transactions eh Professional Communi- cation. 25, 3 (September 1982): 162. Wright, Patricia. "Five Skills Technical Writers Need." IEEE Trans- actions eh Professional Communication. 24, 1 (March 1981): 10-16. Wright, William F., and Donald T. Hawkins. "Information Technology--A Bibliography." IEEE Transactions eh Professional Communication. 25, 1 (March 1982): 43-50. Yourdon, Ed, and Larry Constantine. Structured Design: Fundamentals hf e Discipline 2£ Computer Program and Systems Design. New York: Yourdon Press, 1978.