Home

"user manual"

1. WRITING FOR THE READER by John O Rourke of Digital Software Publications prepared by Digital Software Document Preparation digital equipment corporation maynard massachusetts Copyright 1976 by Digital Equipment Corporation CONTENTS IS THIS BOOK FOR YOU sieneen OF 1 TECHNICAL WRITING AS COMMUNICATION 1 1 A Verbal Communication System The Sender The Means of Transmission The Receiver Noise 2 WHAT THE EXPERTS SAY ABOUT THE WRITER ovare deena i course ieee ce seed 2 1 Gunning s Warning to Technical Writers The Gulf Between Writers and Readers Wrong Attitude Right Attitude The Writer s Purpose Other Faults Noted by the Experts Conclusion 3 WHAT THE EXPERTS SAY ABOUT THE READER scsssscisss were eer re Vaceaees Ok One Reader Profile Another Reader Profile Writer s Grammar versus Reader s Grammar Factors Impeding Comprehension Long Sen tences and Long Words Sentence Structure Position of Information in a Paragraph Posi tion of Adverbial Clauses in a Sentence One Clause Instead of Two Changes in the Logi cal Order of Your Exposition Subject Com plements Instead of Object Complements Factors Increasing Comprehension Principle of Least Effort Understanding and Misunder standing 4 CURING THE FIRST MAJOR ILL THE UNORGANIZED PARAGRAPH 4 Unity Coherence The Haystack Paragraph The Ideal System 5 CURING THE SECOND MAJOR ILL AN
2. Aspects are considering 7 CTRL C is typed by holding down the CTRL key while typing the C key We have two danglers and a verb but no doer When actions occur without an actor 7 7 the whole scene seems as eerie as the movement of the keys on a player piano Another grammatical confusion connected with the passive is the misreading caused by the pronoun it One example from our documentation will illustrate the point The GOTO statement is used when it is desired to unconditionally transfer to some line other than the next sequential line in the program Not until the reader gets to the word to does he realize that it does not refer to GOTO statement Frequent occurrences of the passive with it as the subject throws the reader off stride This is especially so when the structure appears deep in the sentence as it does in this example For the more words that if can refer to the greater the effort the reader must expend to extract the meaning Wastefulness Some critics fault the passive because it requires more words Houp and Pearsall for example state flatly that the passive is uneconomical because it costs more to print more words Let s apply the principle of economy to some sentences in our own documentation Each sentence is shown as it appears in the manual The revision follows it And finally there appears a statement of the saving in words gained by the revision 1 Ori
3. The 1055 is the dual processor equivalent of DECsystem 1050 with fast execution of compute bound jobs because of the addition of the second processor This system has two parallel KA1O processors connected with one operating system in order to double the computing power of the 1050 and at the same time to maintain the same interface between the user and the computing system This approach of co equal processors gives the user increased computing capacity when processing power is in heavy demand under multi task loads In addition to the two KA10 processors the typical 1055 has 80K of ME10 core memories with one MX10 memory port multiplexer one RM10G drum system one RPO3G disk system with up to eight disk packs one TU40G 120KC mag netic tape system one CR10 card reader the LP10C line printer and 32 local lines either a DC10 system or a DC68A system Comment Appearing in this instance at the end the lump gives the whole paragraph a kind of foot heavy look It s like putting size 18 shoes on a person who is five seven And setting aside any further comments on appearance we can say that this lump is as much of a drag on communication as the lumps in Examples 1 and 2 8 11 SUMMARY OF EFFECTS AND REMEDIES The overall effect of density is to greatly reduce your chance of communicating with the reader For one thing a solid chunk of technical matter is likely to repel him because he finds it dull and unnatural It dis
4. 3 Depress the LOCK ON control Step 2 is akin to INBOUND TRAINS ONLY It doesn t tell the reader 1 how to start feeding the tape and 2 how to verify that he has fed it correctly If someone should say that the reader of this manual should know these things then the obvious question arises Why is there an illustration to help him with steps 1 and 3 but nothing to help him with the seemingly more difficult second step The existence of the figure indicating the controls shows that the writer considers the reader to be without experience On the other hand the terseness of Step 2 assumes that the reader does indeed have experience The confusion of such fast pacing in technical writing could leave the reader as frustrated and immobile as the visitor in Boston reading INBOUND TRAINS ONLY for the first time From another point of view fast pacing refers to writing that packs a lot of technical data into few words Seen on this level fast pacing is called density 8 2 This chapter takes a close look at density in technical writing at what it is at the various forms it takes at its effects and at the ways it can be cured WHAT IS DENSITY Density is the bunching together of technical details so closely that the reader cannot read them at his normal reading rate The writer makes little attempt to articu late the details he merely lays them down side by side The impression on the reader is that he is being fed too
5. 33 words Any format conversions and I O control routines not needed in the resident section but required by overlay sections must be forcibly loaded into the resident section This can be done by declaring the appro priate globals in an assembly language routine or inserting dummy FORMAT and Input Output statements in the resident main program for all those routines needed in the overlays and not required in the resident section See Section 9 10 for further details Average Sentence Length 26 words The entry existence indicator is set nonzero when a buffer entry is made When a requester has removed or processed an entry it must clear its existence indicator in order to free the buffer entry position Entries are made in a circular fashion starting at the top low address filling in order of increasing memory addresses to the bottom high address and wrapping around from bottom to top If input data occurs in a burst sufficient to overrun the buffer data is discarded and a count of data overruns is incremented The nonzero entry existence indicator also serves as an overrun indicator A positive value 1 indicates no overruns between entries and a negative value is the two s complement of the number of times data has been discarded between entries 6 8 Word zero of the buffer is used by the handler task as a pointer into the buffer where the next set of interrupt information is to be entered It is expecte
6. All these things considered we can rightly call the communication in Figure 2 effective because the reader s head contains a sizable chunk of the meaning originally in the source You can however further improve the communication Whenever you get feedback from the reader you modify the wording of the language 3 But the transmission can never be perfect That is what makes your task as a communicator continue long after the software has gone to the customer You have to struggle to make 3 clear the first time and then you strive just as hard for clearness each time you modify 3 because of feedback from the reader In this way you 1 4 avoid the defective communication of the secretaries managers etc mentioned at the beginning of this chapter A diagram of their faulty communication appears below Figure 3 IDEAS SOURCE if any IDEAS IDEAS IDEAS SENDER LANGUAGE RECEIVER Figure 3 Faulty Communication of Ideas THE SENDER The blunt truth about the job of communication is that the entire burden of it rests on the writer s shoulders You are the only one to blame if the process fails Hence yours is a vital role And here is a partial list of what is expected of you as the sender in the communi cation system You will get a detailed view of yourself in Chapter 2 WHAT THE EXPERTS SAY ABOUT THE WRITER l 2 You are totally responsible for getting clear accurate information from the source You must g
7. BIG WORDS The modern Humpty Dumpty is adept at using big words those of three syllables or more to cloud his meaning And he often uses them to impress the reader rather than to inform him Indeed his motto seems to be Never use a small word when a big one is at hand The danger of big words lies in their many meanings When readers cannot readily detect the writer s meaning they are likely to pick a meaning at random Thus communication is left largely to chance And as we said in Chapter 1 if the technical writer does not communi cate he is a failure Typical of the big words that tend to mislead are those on this list culled from the first three pages of a DEC software manual We are not saying they should be eliminated Rather we say they can impede communica tion because they are more likely to be misunderstood than the smaller words you can put in their place 9 4 Big Word Small Substitute accordingly sO accomplishes gains activate begin advantageous useful boundary limit capability power consequently sO demonstrate show discontinue stop employs uses encourage urge endeavor try enhances improves environment setting facilitate ease fluctuate vary initial first initiate begin manipulated handled maximum greatest highest numerous many modification change optimum best relinquish release requirements needs subsequent later terminate end utilization use But combinations of big words create the d
8. DLO by a factor of two The number of data points may also be changed to some arbitrary value DPO and viewed via a window DWI The table delta DTA used in selecting data points for display can be varied The ability to define the zero data position of a display BDD and show the data expanded to the scope limits DNO is provided The buffer identification name DID in conjunction with the free DFV I Teletype is aregistered trademark of the Teletype Corporation 8 5 and fixed DCV cursor values may be displayed It is essential that a display be active in order that all display control commands work efficiently Comment What an awesome pile of tech nical data to squeeze into a single paragraph Again this is a mere catalog of details with absolutely no attempt to relate or interpret them This information would be far more effective in a chart or table Notice that it is impossible to insert logical connecting words or transitional expressions in a paragraph like this In fact the inability to put in such words and expressions is a mark of the stuffed paragraph Random access files unlike sequential access files do not distinguish between read mode and write mode The user can read or write any item in a random access file at any time by first setting a pointer to that item A random access file contains either string data or numeric data but not both Each data item in a random access file takes
9. Dan Slobin writing in the JOURNAL OF VERBAL LEARNING AND VERBAL BEHAVIOR in 1966 adds the negative passive is even more complex than the positive Slobin tested subjects who ranged in age from 6 to 20 All of them found the negative passive the hardest of all sentences to understand Concealment Experts find the passive defective because it often fails to identify the doer Some critics call this the case of the lost subject or the missing agent It would be amusing if the failure did not sometimes have serious consequences All doors in this building must be locked before you leave work for the day Who s going to lock them Chances are that no one will because the directive does not specify the doer At other times the missing agent poses no serious problem Once these statements are mastered the user can investigate the more advanced applications of these statements and the additional statements and features explained in Parts II and III DEC manual In this instance the reader can leap without strain to the conclusion that the user is the doer But why not make the doer explicit and thus remove all uncertainty After mastering these statements the user can investigate the more advanced applications of these statements and the additional statements and features explained in Parts II and III Misconstruction The passive increases the likelihood of grammatical errors This is especially so in the case of
10. Doer is unimportant The input and output units are combined in Figure 2 1 because in many cases the same device acts as both an input and an output unit Comment Emphasis is on the receiver doer is unimportant Winter wheat is harvested in Saskatchewan Comment Doer is unimportant The airplane was loaded in Saigon yesterday morning Comment Doer is unknown very likely unimportant The first instruction of the subroutine is put in the second location of the subroutine Comment Doer is unimportant Rubouts are not stored in the text buffer but are inserted by the Editor following all tab characters on the output tape Comment Emphasis is on the receiver 9 A validation error is flagged when the information written is not the same as the information read in Comment Doer is unimportant THE PASSIVE IN LITERATURE AND TECHNICAL WRITING Thomas Johnson in his book ANALYTICAL WRITING says that active verbs predominate in good literature In Lincoln s Gettysburg Address he points out only 3 verbs out of the 30 are passive In Hamlet s To be or not to be there are only 2 passive verbs out of 25 And in the Twenty third Psalm King James Version not one of the 15 verbs is passive Quite in contrast to these figures are the proportions in technical writing Three pages in DEC software manuals sampled at random show the following breakdown Manual Page Verbs Passive BASIC
11. G T From ERIC Source Documents to Abstracts A Problem in Readability Educational Resources Information Center U S Office of Education Document Number ED 086243 1973 Lively B A and Pressey S L A Method of Measuring the Vocabulary Burden of Textbooks Educa tional Administration and Supervision Volume 9 pages 389 398 1923 Lowe H Solomon or Salami Atlantic Monthly Volume 204 pages 128 131 1959 Marcus A Reading as Reasoning Reading as Am biguity Understanding Sentence Structures Educational Resources Information Center U S Office of Education Document Number ED 086950 1971 McCullough C M Preparation of Textbooks in the Mother Tongue A Guide for Those Who Write and Those Who Evaluate Textbooks in Any Lan guage Educational Resources Information Center U S Office of Education Document Number ED 082120 1965 McGintitie W H and Tretiak R Sentence Depth Measures as Predictors of Reading Difficulty Reading Research Quarterly Volume 6 pages 346 377 1971 Meyer B J F Structure of Prose Identification and Effects on Memory Educational Resources Infor mation Center U S Office of Education Docu ment Number ED 076979 1973 Meyer B J F and McConkie G W Effect of Position of Information in a Passage s Organizational Struc ture on Recall Educational Resources Informa tion Center U S Office of Education Document Numbe
12. cannot concern yourself merely with putting words on paper as does the writer of a diary or the ill fed poet in a garret These people can enjoy the luxury of self expression They can exist without readers Or they can if they wish write to parade their knowledge before the reader rather than to convey it to him But you must concentrate on how best to convey meaning to the reader you must strive to make your sentences mean the same to him as they do to you It s too bad in a way that the term technical writer is used at all The writer part of it has lost most of its meaning Doesn t everyone write The answer to that question is all around you Programmers write managers write marketing people write secretaries write Look at the mountain of memos and reports these people produce As each day brings a stream of such papers across your desk you re forced to strain eye and mind to discover meaning amid the welter of words Sure everyone can write But daily experience tells you only a few can communicate In this book we will often use the term communicator instead of writer In doing so we realize we re replacing a word of two syllables with one of five but we think the longer term is more descriptive of the unique skill of the technical writer Consider for a moment the origin of the word communicator It comes from the Latin communis which means common And as we ve already emphasized the main business of the tech
13. compressed and compact But no matter how it is described it can always be identified by a sometimes disturbing characteristic it leaves much information unsaid Thus in assuming a large background of knowledge on the part of the reader such writing often leaves him more baffled than informed with more questions than the text can answer Look for instance at what the sign INBOUND TRAINS ONLY does not say It does not tell the new visitor that this entrance leads to cars marked Park Street and Lech mere or that Park Street cars go just one stop to Park Street and then he ll have to get off or that Lechmere cars go to Park Street and beyond to Government Center Haymarket and Lechmere or that he can alight at Government Center and make connections with rapid transit cars to East Boston or that he should take the entrance across the street to get to Copley Square All this information is implied in that one sign But there is no way this reader can know any of it let alone all of it Without someone to supply such details he is lost immobilized unable for a time to proceed any further Many times the fast pacing of technical writing does the same thing to the reader For example look at the three instructions given below They are taken from a DEC software manual for relatively new users 1 Turn the Teletype control to LOCAL see Figure C 1 2 Feed the blank tape into the punch
14. documents you use to get the facts for your writing This meaning will always be different from the meaning 2 that lodges in your head after reading those documents The degree of difference depends on your skill in interpreting the language of the source Notice in Figure 2 that the size of 1 and 2 is roughly equivalent The difference occurs mainly around the edges This happens whenever words are used in the source for words are variable in meaning Thus you will interpret some words right and others wrong But the greater your skill in decoding the language of the various documents the more the data in your head will approximate that of the source You further distort and lose meaning when you start to write For one thing you aim to write only what the reader needs to know Thus you must select certain facts from the array in your head and reject others Secondly since most of the words you choose have multiple meanings you always send additional if unintentional meaning along with your technical facts For these reasons 3 in the diagram is different from 2 Happily in this instance it is only slightly different Finally the receiver or reader extracts a different meaning 4 from your written language because it is impossible for all the words to mean the same to him as they do to you Thus the meaning that ultimately resides in the reader s head is different in various respects from the other three meanings
15. pages 59 62 1973 Van Rooy L Readability Studies and the Writer of Instructional Materials Educational Resources Information Center U S Office of Education Document Number ED 089245 1973 Von Glasersfeld E The Problem of Syntactic Com plexity in Reading and Readability Journal of Reading Behavior Volume 3 pages 1 14 1971 Walker R V The Technical Language Dimension An Analysis of Contributing Factors Dissertation for Doctor of Philosophy Degree University of Cali fornia Irvine 1972 Weaver W W Kingston A J Brickley A C and White W F Information Flow Difficulty in Relation to Reading Comprehension Journal of Reading Behavior Volume 1 pages 41 49 1969 Williams D L The Effect of Rewritten Science Text book Materials on the Reading Ability of Sixth Grade Pupils Dissertation for Doctor of Educa tion Degree University of Illinois 1964 Williams M and Stevens V M R Understanding Para graph Structure Journal of Reading Volume 15 pages 513 516 1972 R4 BOOKS The books marked with an asterisk are recommended in their entirety to the new technical writer Barzun J and Graff H F The Modern Researcher Harcourt Brace and World Inc New York 1957 Black M Critical Thinking Prentice Hall Inc Engle wood Cliffs New Jersey 1952 Blicq R S Technically Write Prentice Hall Inc Englewood Cliffs New Jersey 1972 B
16. paragraphs of his exposition In any piece 2 10 of technical writing Thomas Johnson says no matter how difficult the opening para graphs should be intelligible to every inter ested reader Don t avoid technical terminology but simplify the language around it Example This is the paragraph labeled Introduction in Chapter 3 of a DEC document The AFC11 and ADO devices are used for industrial and laboratory analog data acquisition The AFC11 is a flexible high performance multi channel analog to digital A D converter Under program control the AFC11 performs a 13 bit A D conversion at a rate of 200 channels second The AFC11 can multiplex a maximum of 1024 differen tial input analog signals The ADO is also a multi channel A D converter however it differs from the AFC11 in that it multi plexes up to 64 analog signals In the following sections the AFC11 device handler task is discussed first and then the ADOI device handler is described Comment Actually this paragraph of introduction causes more reader pain than the technical description of the AFC11 device handler task that follows it The writer s presentation of detail is so dense that reader cannot absorb all the ideas at his normal reading pace Example The paragraph in No 5 illustrates this fault Comment The word dense refers to the clustering of ideas In the preceding para graph density appears in such ex
17. rich a diet of technical information The common forms of density in technical writing are 1 adjective strings 2 stuffed paragraphs 3 un explained series and 4 lumpy paragraphs Adjective Strings In this form there is a high concentration of technical terms in front of a noun The terms are either normal adjectives or adjectives made from nouns Two examples from DEC software manuals appear below 1 The AFC11 isa flexible high performance multi channel analog to digital A D converter Comment Here flexible high performance multi channel and analog to digital are all adjectives qualifying converter They com press a wealth of technical data into a small space For example take flexible and high performance A paragraph or two could be written on each one But as they now stand the writer hasn t bothered to define and analyze them for the reader They are merely part of a cluster of details before a noun And the reader is left with the job of interpreting them 2 Because of the interactive conversational rapid response nature of timesharing a wide range of tasks from solving simple mathe matical problems to implementing complete and complex information gathering and processing networks can be performed by the user 8 3 Comment This sentence contains two instances of piling up What heightens the pain of the first one is that the adjectives are piled up before an abstract
18. speaking people A would have to know the word perro In fact the very existence of different languages proves there is no direct connection between words and things So the connection between any word and what it refers to lies in the minds and experiences of the writer and the reader The writer depends on the reader to relate the word to its referent But what is clear to one class of reader may be as meaningless to another as the word dog is to people who know only chien or perro THE LADDER OF ABSTRACTION As soon as we use a word say dog we start the abstraction process For there is no such thing as dog in the real world Out there exist Fido and Rex and Prince and all the other individual dogs with their individual names and individual characteristics What we have done with the word dog is make it refer to certain selected characteristics of all dogs In doing so we left out other specific characteristics of individual dogs This is the essence of the process of abstraction we leave out certain specific characteristics Thus we use dog to mean in the words of the ENCYCLOPEDIA AMERICANA a domesticated car nivorous mammal remarkable for its intelligence and its attachment to man What have we left out For one thing we say nothing about overall size shape of head or the color or kind of fur Nor do we mention the sound dogs make their odor or their sleeping and eating habits To
19. then good jargon becomes bad jargon For in its derogatory sense jargon refers to terms and expressions that are unclear either 1 because the audience is unfamiliar with them or 2 because writers attach new private meanings to them This second category is designed to impress the reader to make him think the author is smart because he is in Such words may once have been the good jargon of a trade or profession But they have since been robbed of their precise meaning Now they are used by vague thinking writers to hide the vagueness of their thinking Some examples of computer terms now labeled bad jargon appear below capability maximum support component operation compute bound optimization computing power processing power concepts program parameter input data values reliability environment sophistication facility stand alone system features system high level language system resources high speed performance technique implementation utilization installation Such words dare the reader to find out what they mean But worst fault of all they convey foggy ideas On this ground they should be shunned as poor communication tools Another example of bad jargon i e foggy words is the too easily coined ize words Certainly we have a huge number of good ize words pasteurize sterilize magne tize oxidize galvanize anesthetize phosphorize etc The bulk of these are precise scientific terms But in a way th
20. there is little unity and practically no coherence The writer should try breaking the paragraph into three parts as the first step in im proving it One paragraph could be devoted to read and write mode another to records and the last to strings In addition the writer should show explicitly the relationships among the facts so that the reader is helped through the text That is the writer should be liberal in the use of connectives and transitional expressions Scheduling may be forced before the time slice has expired if the currently running job reaches a point at which it cannot imme diately continue Whenever an operating system routine discovers that it cannot complete a function requested by the job e g it is waiting for I O to complete or the job needs a device which it currently does not have it calls the scheduler so that another job can be selected to run The job that was stopped is then requeued and is scheduled to be run when the function it requested can be completed For example when the currently running job begins input from a DECtape it is placed into the I O wait queue and the input is begun A second job is scheduled to run while the input of the first job proceeds If the second job then decides to access a DECtape it is stopped because the DECtape control is busy and it is placed in the queue for jobs waiting to access the DECtape control A third job is 8 7 set to run The input operati
21. 12 3 13 sequential 3 12 chronological 3 12 Order of ideas 2 1 3 13 Opening paragraphs 2 10 Organization 2 2 4 1 lack of 2 3 poor 1 7 tight 4 1 Pacing fast 8 2 Pallid passives 7 4 7 11 7 15 Paragraphs haystack 4 10 length of 8 8 main idea of 2 10 opening 2 10 organization of 4 2 4 9 per page 3 14 position of information in 3 10 structural 3 14 unorganized 4 1 4 13 Passive in literature and technical writing 7 14 Passive voice 1 7 2 8 7 2 abstractness of 7 12 case against 7 1 7 4 case for 7 12 complexity of 7 5 concealment 7 5 Index 5 INDEX Cont deemphasis 7 11 misconstruction 7 6 negative 7 5 recognizing the 7 1 shifting to the active from 7 1 7 15 wastefulness of 7 10 wordiness of 7 10 Pearsall Thomas 6 7 Perceptual complexity 3 13 Phrase choppy 2 9 Picturable words 5 6 5 9 Position of adverbial clauses 3 11 Principle of least effort 3 14 8 12 Profile of reader 3 1 Prospective ambiguity 3 10 6 2 Punctuation 2 1 Purpose of exposition 1 6 Readability 2 6 3 1 3 14 6 6 6 10 Readability tests 3 1 6 6 Reader 3 1 burden of interpretation 4 11 challenging the 3 14 comprehension 4 5 defrauded by writer 4 12 educational level of 3 2 energy of 3 8 3 9 examples familiar to 3 3 eye movements of 3 7 focusing attention of 4 2 grade level of 3 14 image of 3 1 3 4 inefficiency of 3 4 3 6 3 8 3 10 3 11 3 12 3 14 3 15 memory of 3 9
22. 3 11 6 3 6 6 8 7 mental power of 3 9 motivation of 3 2 3 14 needs of 1 4 1 6 2 10 3 1 3 4 8 5 8 12 normal reading pace of 2 11 poor 3 5 3 6 3 7 3 14 processing information 34 publications depend on 2 2 remembering facts 6 3 specialized background 3 2 template of 3 4 Index 6 INDEX Cont terms familiar to 3 3 typical 3 4 voluntary 3 2 wants of 2 3 Reader and complex sentences 3 6 Reader orientation 3 14 Reader profile 3 1 administrator or technical person 3 4 attention to the material 3 3 intellectual level 3 3 interests 3 3 selecting a reader 3 4 subordinate in knowledge 3 3 superior in knowledge 3 3 Readership 2 6 3 5 Reading errors 3 6 Reading level and grade completed 3 2 Reading of textbooks 3 5 Receiver 1 3 1 4 1 6 Receiver of the action 7 3 Reference unclear 2 7 Relationship between words and the external world 5 1 Relationships in writing 2 2 cause and effect 4 12 implied logical 4 11 logical 4 11 Relevance 2 2 Required memory level 6 3 Revision 2 5 Schools better 3 5 Self expression 1 2 1 6 2 3 Sender the 1 3 1 5 Sentences burdensome 6 4 complexity of 1 7 6 1 6 10 length of 6 6 long 2 4 loosely associated 4 7 short 2 3 2 5 3 7 3 14 6 6 6 7 tightly linked 4 7 Sentence structure 3 9 Sequential order 3 12 Shifts of topic 4 5 Index 7 INDEX Cont Shima Fred 4 1 Short words 2 5 3 7 3 14 9 6 Signals 4 12 Si
23. ABSTRACT STYLE sc sce cnc ese petowes gar coed Language and Reality The Ladder of Abstraction Abstract Words vs Concrete Words What s Good About Abstract Words What s Wrong With Abstract Words Making Abstract Sentences More Meaningful Summary iji CONTENTS Cont 6 CURING THE THIRD MAJOR ILL SENTENCE COMPLEXITY e0 Required Memory Level Sentence Length Some Suggestions for Reducing Complexity 7 CURING THE FOURTH MAJOR ILL OVERUSE OF THE PASSIVE VOICE Recognizing the Passive The Case Against the Passive The Case for the Passive The Passive in Literature and Technical Writing Shifting from the Passive to the Active 8 CURING THE FIFTH MAJOR ILL FAST PACING AND DENSITY What is Density Adjective Strings Stuffed Paragraphs Unexplained Series Lumpy Paragraphs Summary of Effects and Remedies 9 CURING THE SIXTH MAJOR ILL FOGGY Jargon Big Words Deadwood Summary REFERENCES eeesee ereee eteoeeeeoeee 17efterettoenweeeoeet ees eee Dissertations and Monographs Books Recommended Reading iv IS THIS BOOK FOR YOU You should answer this question before you turn to Chapter 1 This book is for you if you are first of all a person who has a firm grasp of a technical subject but is rela tively weak in the principles of written communi cation That is not to say that you have no back ground in English Rather you ve had the usual high school English
24. N V Publishers The Hague 1968 Shurter R L Williamson J P and Bruehl W G Business Research and Report Writing McGraw Hill Book Company Inc New York 1965 Sklare A B The Technician Writes A Guide to Basic Technical Writing Boyd and Fraser Publishing Company San Francisco 1971 Strang B M H Modern English Structure William Clowes and Sons Limited London and Beccles 1963 Ulman J N Jr Technical Reporting Henry Holt and Company New York 1952 UNESCO Bibliography of Publications Designed to Raise the Standard of Scientific Literature Unipub New York 1963 Weisman H M Basic Technical Writing Charles E Merrill Books Inc Columbus Ohio 1962 INDEX Abstract words 1 7 2 3 2 8 5 1 5 2 5 3 5 4 5 5 5 6 5 7 5 8 5 9 5 10 5 11 5 12 5 13 7 12 8 4 Abstract words as tools of thought 5 6 Abstract words vs concrete words 5 5 Abstraction high level of 5 9 Abstraction ladder 5 2 5 3 5 4 5 11 5 12 Abstraction process 5 2 Abstractions detrimental 5 8 Active verbs 5 7 5 12 Active voice features of 7 2 Adverbial clauses position of 3 11 Adverbs of time 4 9 Ambiguity 5 7 5 8 5 10 Ambiguity prospective 3 10 6 2 Artificiality wall of 2 4 Ascending the abstraction ladder 5 3 Barzun Jacques 2 7 4 7 5 11 5 12 Big words 2 3 9 1 94 Boldface typography 3 3 Bormuth J R 3 5 3 6 Boyd L G 7 15 Breach of contract 4 5 4 6 Burden
25. PLUS 2 3 21 10 Sept 1974 DECsystem 10 3 1 21 10 BASIC RSTS E SYS 3 74 29 13 MANAGER S GUIDE To show how indiscriminate use of the passive results in unnatural prose Johnson passivized the Twenty third Psalm To be sure few people would ever write some of the sentences he produced but the passage can serve as an extreme to remember when you monitor your own writing The Lord is designated as my shepherd nothing shall be wanted by me I am made by him to lie down in green pastures I am led by him beside the still waters 7 14 My soul is restored by him I am led in the paths of righteousness for his name s sake Yea though the valley of the shadow of death is walked through by me no evil will be feared by me for I am accompanied by thee I will be comforted by thy rod and thy staff A table is prepared by thee in the presence of my enemies my head is anointed with oil by thee my cup is made to run over Surely I will be followed by goodness and mercy all the days of my life and the house of the Lord will be dwelled in by me forever SHIFTING FROM THE PASSIVE TO THE ACTIVE Shifting to the active from the passive automatically improves a writer s style This is the view of authors Menzel Jones and Boyd in their book WRITING A TECHNICAL PAPER But don t interpret this quotation to mean improvement comes when all passive verbs are changed to the active The passive we repeat has a place in
26. WRITING Either they produce what the reader wants or they go out of business because the reader goes elsewhere Such in Gunning s opinion is not the case with technical writing The technical audience cannot simi larly make its demands felt because it cannot go elsewhere for its technical information Thus the tech nical writer can afford to write in a vacuum But this situation will not last forever Eventually the demand _ for more readable technical writing will be as effective as was the demand for more readable magazine articles THE GULF BETWEEN WRITERS AND READERS When talking about writers Gunning pulls no punches He boldly asserts that the writer has created a wide gulf between himself and the reader a gulf impeding the communication of ideas And he goes on to describe the distressing situation The gulf between writers and readers is very great Readers want careful organization in what they read They desire concreteness to help them picture and apply ideas They like variety it maintains their interest They prefer short but variable sentences and not too rich a mixture of hard words Writers on the other hand enjoy self expression They would as lief use abstractions to which they give their own special meanings And a writing job goes easier and faster if you can simply set down the facts without the exacting thought needed for careful organization Here Gunning is speaking about writers in
27. a good target to aim for Reducing sentence length doesn t mean you ll confine your presentation to simple sentences No you ll still balance and mix simple sentences with compound and complex though the proportion of simple sentences will doubtless increase What you will do however is reduce the number of subordinate clauses phrases and other modifiers in each sentence To illustrate how our documentation would shape up against the Flesch and Houp Pearsall measures let s analyze some passages chosen at random Here are the paragraphs the analyses follow 1 These procedures might include but are not limited to relationships between trans actions and data bases and responsibilities of the users and data base personnel In order to fully accomplish all the tasks assigned to him and his staff the Data Base Administrator should schedule time when the data base is not available to users in order to perform reorganization procedures such as reassigning areas to different devices media FAILSAFE procedures and other house cleaning chores This time is in addition to the normal preventive mainte nance time for the computer system as a whole and the users must be made aware of these activities Likewise users who merely want to retrieve information from the data base should know when this information is being updated by other users so that fresh copies of data are always available Average sentence length
28. an excellent ex ample of a case where the reader doesn t sense ambiguity He merely supplies his own meaning and moves on Example Lab Applications 11 is an inte gration of software hardware and theory which provides the laboratory computer user a combination of resources to solve his particular laboratory application problem 5 10 Comment Try if you can to state the meaning of integration of hardware and theory Then try integration of software and theory In this way you ll get some idea of the emptiness of the entire phrase integration of software hardware and theory Example Consider a research company which is organized into departments Some of these departments are actively engaged in research others are support departments e g accounting payroll legal etc Each research department is broken up into re search project groups although there are some special projects which overlap depart ments The research projects are supported by contracts and grants which come from external sources some projects receiving funds from more than one contract or grant Comment At first glance this paragraph seems more concrete than the others But it is still on a high level of generality Witness words like departments projects research research project groups and grants The wiiter failed to give these specific meaning even though he intended this description as an examp
29. anyone come up with one of the pallid passives that abound in technical writing is accomplished is designated is observed is achieved is established is performed is allowed is effected is permitted is arranged is employed is provided is assigned is enabled is required is attained is facilitated is specified is based is featured is used is considered is involved is utilized is defined is made So the first point in the case against the passive is that it usually weakens the force or impact of the sentence And you can sense the general truth of this contention by observing the feebleness of the passive in these sentences 1 No moss is gathered by a rolling stone Early in the morning a utility pole was crashed into by a speeding car 3 Except where specified each line typed by the user must be entered to the computer by typing the RETURN key DEC manual 4 The worm is caught by the early bird 7 4 5 The international dateline was crossed by the airplane 6 This was immediately realized by me Complexity A second point is that the passive is harder to understand than the active The reader feels that the passive sentence is unnatural Its subject is the receiver of the action rather than the doer And this says researcher Alvin Granowsky disconcerts the reader because he expects the subject to be the doer Thus with the passive he has to keep track of the doer a chore the active does not impose To all this
30. but the meaning remains unchanged Invariably this is what happens when empty words like nature are deleted Similar examples follow DEADWOOD PROPERLY Example After the group of modifications have been added to the file RUNOFF produces a new copy of the file which is properly paged and formatted Revision After the group of modifications have been added to the file RUNOFF produces a new copy of the file which is paged and formatted Comment Here we can assume that paging and formatting are going to be done properly especially when we re touting our own software DEADWOOD SUITABLE Original TECO manipulates data within the editing buffer in response to suitable commands from the user Comment Delete suitable In a manual that describes all TECO commands the notion of suitability does not have to be spelled out The reader knows he won t get anywhere with the software unless he uses a suitable i e legitimate command Original The listing can be directed to any suitable output device line printer teletype DECtape or disk 9 8 Revision The listing can be directed to an output device line printer teletype DECtape or disk Comment Labeling the devices as suitable is needless when they are listed DEADWOOD ASSOCIATED Original The DECsystem 10 is more than a processor and its associated peripheral devices Comment Delete associated The word its shows th
31. from written material They are likely to misunderstand big words and misinterpret long complex sentences Another view of American readers almost as startling as Bormuth s was given by Helen R Lowe in an article in the November 1959 issue of ATLANTIC MONTHLY She worked for many years with superior tenth eleventh and twelfth grade students She found them making such disturbing reading errors as the following Word Appearing in Book Word Read by Student delicacy delinquency bivouac bifocals timid diminished groceryman clergyman hurricane hammer bos n cow neurosurgeon trapeze phosphate phosphorous hydride hydroxide God knows good news antiseptic adhesive Oxonian example inert inherent industrial international imbecility implicitly Solomon salami To darken the picture still more she said this is just a sample from a list of some 100 000 errors by excellent students all the way up to the college level Add to these misreadings the errors in comprehension arising from distorting the tenses of verbs and applying modifiers to the wrong words and the picture of reader inefficiency gets even worse Once again what is the significance of all this to you as a communicator Two observations are relevant One is reinforcement of the notion that you cannot generalize about readers on the basis of your own good reading ability Take it as gospel that readers are generally not as good as you are In fact they are much wors
32. gets to the verb he knows what the subject means in this sentence This is an important aspect of required memory level it is usually equated with the distance between subject and verb Many word puzzles Morris points out are based on required memory level The following one has been around a long time If a hen and a half lays an egg and a half in a day and a half how many eggs does one hen lay in a day Another familiar oldie asks the reader to identify the person who says these words while looking at a picture Brothers and sisters I have none But this man s father is my father s son 6 3 Some technical writing imposes a burden as great as that of the word puzzles Here is an example from one of our manuals Systems for digitizing and storing analog data sorting and averaging multiple analog signals and sequencing processing events are all examples of laboratory problems where DIGITAL has knowl edge independent of scientific discipline In this case the reader must temporarily store and remember 13 facts before the predicate lets him know what they mean Admittedly there are individual variations in the capacity to cope with a required memory level But retaining 13 facts would be a prodigious feat for even the most retentive of memories Just for the fun of it reread that sentence and when you reach the word problems try to remember the three problems This exercise puts you in the place
33. included the big cities the percentages would have been higher What do Bormuth s percentages mean in concrete numbers Well each year American high schools grad uate about 3 million students In fact in 1969 the year immediately preceding Bormuth s report our high schools graduated 2 839 000 students Of the nearly 3 million graduates remember that Bormuth s percent ages would likely be higher if he considered the cities at least half cannot read their textbooks And what s even more jolting these students are in a situation where they can get help in reading their texts What does this mean for you as a technical communi cator At the outset let s agree that not all these people went to work for factories and diners or joined construction crews There s nothing to indicate they re unintelligent They just cannot read well Doubtless many of them went on to become secretaries clerks technicians computer operators key punch operators programmer aides etc Aged 22 and 23 today they probably form part of the readership of your manuals Surely the way events fall out some of them will become managers and assistant managers of data centers And when you add the number of illiterate graduates this year to that of last year and the year before and so on you should gather that at least half the adult population of the United States has trouble reading Such people have a difficult time getting meaning
34. is a much less serious offense than the previous two it still causes the reader to wonder what is going on in the writer s mind Concurrently and even while have the same meaning Writers should delete concurrently and even The writer fails to put his main idea at the beginning of the paragraph Suspense according to Thomas Johnson defeats the purpose of exposition The information the reader needs to know should be at the beginning Example This mode should be used with caution When this option is assembled in the module GTRCAL and DISSKP are used in combination to determine what is to be done to the display file This mode is provided for the careful user who has one or more curves being displayed and wishes to change one or more of them without turning off the display while it is being done To do this the user must first create the display file with GTRCAL set to 1 and DISSKP set to 1 in all INIT DISPLAY tables To recalcu late the display file set GTRCAL to 1 and for any INIT DISPLAY table which is not to be calculated clear DISSKP DISSKP will be reset to 1 upon return The user in effect is saying that the space required for recalcula tion of each curve will not exceed that required initially Comment The first two sentences do not contain the main idea of the paragraph The third one does It should be the first sentence in the paragraph The writer failed to simplify the opening
35. is called a subject complement In Sentence 2 it is called an object complement Although the clauses are identical the one in Sentence 1 is in the words of V M Holmes significantly more difficult to understand His explanation focuses on the occurrence of the main verbs In Sentence 2 the main verb comes early so you know the main idea of the sentence as soon as you reach the third word In Sentence 1 the main verb comes late so the reader has to carry from 10 to 12 words in temporary memory before the meaning of the sentence is resolved for him Processing the main clause first Holmes concludes decreases perceptual complexity and increases comprehension FACTORS INCREASING COMPREHENSION Here are some tips on how you can help the reader comprehend your exposition 1 Be logical in your presentation Decide ona systematic order and stick to it 2 Use explaining links such as because there fore so if then as a result etc They call attention to the logic of your thinking by pointing out a cause means or result Chapter 4 tells you more about links or transitions 3 Introduce examples frequently especially where the material is difficult 4 Let daylight into your copy Long para graphs have an unfavorable psychological effect on the reader Break them up Maybe 3 or 4 paragraphs a page would be a realistic goal As Robert Gunning says Readers like periods and white space 5 Make you
36. is nothing then ask yourself What am I trying to say What am I trying to tell the reader Similar to Gunnings s advice is Jacques Barzun s and Henry Graff s suggestion that you constantly ask Can this be touched or seen Coleman and Miler say that much writing is difficult to understand because the writer chooses verb nominalizations instead of verbs A verb nominalization is an abstract noun derived from a verb For example operation construction and creation are verb nominalizations derived from the verbs operate construct and create respectively Coleman and Miller conclude that the writer can make his sentences more meaningful by reducing the number of verb nominaliza tions You do this by changing the verb nominalization into an active verb Thus you would change Peter s creation of the program to Peter created the program Gunning a very articulate proponent of the use of short words suggests that you use big _words sparingly Most big words he points out are abstract They stand for qualities of 5 12 things and relationships among things Short words on the other hand are concrete they refer to persons places things and acts 6 Thomas Johnson asks you to spot fuzzy words in your own writing and then either eliminate them or give them specific mean ing Typical words that tend to make your style abstract appear in the following list ability extent practice achievement feat
37. must struggle too much with complexity he cannot process the information properly for recall later What does all this mean to you as a technical writer The answer is simple Make your sentences less complex in order to communicate successfully In this chapter you l find a discussion of required memory level and sentence length in their relationship to complexity And the closing paragraphs offer you some suggestions for the cure of this major ill of technical writing REQUIRED MEMORY LEVEL One way to understand sentence complexity is to view it as a burden on the reader s memory Jackson Morris coined the term required memory level to describe this burden Required memory level as he uses it refers to the reader s capacity to remember facts and relationships as he reads More specifically it means the maximum number of facts he must remember at any point in the sentence Thus the larger the number of facts to be remembered the greater the complexity of the sentence In other words if the required memory level is high the sentence is difficult for the reader The more facts the reader must remember the harder he must work to understand your writing As a simple example look at this sentence _ The fifth house on the right on Dan s street is being sold The reader has to remember four facts fifth house right and Dan s street before he reaches the verb which clarifies the subject for him That is when he
38. noun Even so the second one is more burdensome to the reader because there is a very real question as to the meaning of implementing com plete and complex information gathering and processing networks If the reader expects to learn something from this sen tence he ll be disappointed Happily this kind of density is fast disappearing from DEC software documentation Stuffed Paragraphs j In this kind of density the paragraph is packed to the bursting point with technical details For the most part they are unanalyzed and unconnected One thing all such paragraphs have in common is They cannot be read and digested at a normal reading speed Rather they have to be poured over laboriously at pretty much the speed used to decipher code or to locate an item in a catalog of television parts Here are four stuffed paragraphs from our software manuals 1 The DC71 remote batch station consists of a PDP 8 I processor an operator Teleypte a card reader a line printer and a synchro nous interface The DC71 connects to the DS10 or the DC75 via a full duplex synchro nous communications link The remote batch terminal can be either a DC71A or DC71B terminal The DC71A is configured with a 132 column line printer with a 64 character set The DC71B is configured with a 96 character set line printer The DC71D Teletype Concentrator package includes eight lines for connecting to the DC71A or DC71B Another eight lines can
39. of communication 1 5 Catalog of facts 4 10 4 13 Cause and effect relationships 2 9 4 12 Chief concern of writer 2 6 Chronological order 3 12 Clark H 3 11 Clause length 3 11 Clearness 1 7 2 2 Coherence 4 1 4 6 4 7 4 8 4 9 8 7 Coleman E B 3 7 5 7 5 11 5 12 6 5 6 6 Communication art of 1 5 burden of 1 5 3 15 effective 1 4 1 5 1 6 failure of 3 7 faulty 1 5 5 8 improvement of 14 poor 1 7 successful 6 3 Index l INDEX Cont Communication system 4 13 Communicator 1 2 3 5 3 6 3 11 6 5 6 6 more effective 4 13 responsibilities of 1 5 Communis 1 2 Competence in thinking 2 2 Competence level in writing 2 1 2 2 2 4 2 5 2 6 27 2 12 4 7 Competitors manuals of 2 6 Complex simplifying the 1 6 Complex sentence 1 7 6 1 Complexity perceptual 3 13 Complexity temporary 6 5 Compound sentences 6 10 Comprehension 3 6 3 7 3 11 3 13 Comprehension difficulty 3 11 Concrete examples 5 12 5 13 Concreteness 2 3 Concrete reference 5 4 Concrete word 5 5 5 6 Conditional clause 3 10 Conjunctions simple 4 9 Conjunctions subordinate 4 9 Connected ideas 4 7 Connectives 4 1 4 11 4 12 8 7 8 12 Connotation 1 6 Consistency 4 2 Continuity 4 6 8 12 Contract between writer and reader 3 12 4 2 4 5 4 6 Conversational style 2 5 Dangling modifiers 7 6 Dansereau Donald 3 8 Darnell E K 3 12 Deadwood 9 6 Decoding the m
40. present is for data bases which are suitable for 4 11 processing by and available to multiple ap plications Three cause and effect relationships reside in this para graph but the writer uses no signals like because since thus or therefore to reveal them to the reader The reader is forced to dig them out if he s interested And if he s not interested he misses the whole content of the passage Pause for a moment to consider how the writer of this paragraph defrauded the reader At the time of writing he must have had ideas similar to the following in his mind 1 Because data bases are increasing in use and complexity management by individual ap plication programmers must give way to centralized control 2 Because the creation of data bases for single applications costs so much individual pro grammers will soon stop creating them 3 Because of the cost and the increase in use and complexity programmers must create data bases that multiple applications can use But when he wrote about the contents of his mind he withheld the most important elements the logical connections Thus he made a mystery out of what should have been a revelation The upshot is that he either overworks the reader or loses him entirely Although the final haystack example is long it is worth including because it contains most of the deficiencies of haystack writing Each line of the program begins with a line numb
41. since where because when wherever while But not all the paragraphs in technical writing are as unified and coherent that is as organized as the two you ve just read Indeed many technical paragraphs are almost devoid of guiding words And because they lack the organization that coherence supplies they place the entire burden of interpretation on the reader In effect the writer says to the reader Here are the facts You connect them The typical example of such unorganized writing is the haystack paragraph It is also called the catalog or grocery list paragraph The Haystack Paragraph At DEC a short time ago a programmer returned a manual she had been reviewing to the supervisor of the writing group where it had been written The supervisor asked her how she liked it She was hesitant in her reply I don t know she said There s something wrong but I can t put my finger on it He asked her whether it was accurate She said Oh technically it s all right All the facts are there But it s just She paused and shrugged Weli you have to work too hard to read it As soon as the supervisor looked at the manual he spotted the trouble it was filled with haystack para graphs These are clusters of technical facts swept into neat paragraph piles by the technical writer who gives the reader little or no guidance Here is an example of the kind of paragraph that appears of
42. stylistic choice of the individual doing the writing Actually the material on the JMS instruction is wholly relevant because that instruction is intimately related to inter mediate tasks Notice how the writer repeated the term intermediate task in the third last sentence to reinforce the unity of the subject matter The term was first used in Sentence 2 Notice too that the one sentence that is slightly off the topic is properly placed within paren theses Notice finally how the last sentence carried the reader smoothly into the relevant example It s too bad Robert Gunning did not come upon writing of this caliber before he wrote his TECHNIQUE OF CLEAR WRITING It could have altered his undeniably 4 3 pessimistic view of technical writing And remember that we are now analyzing the paragraph for unity only We re saying nothing about it being clear and exact Nor do we mention the skillful use of transitional words these such after thus etc to tie the whole paragraph together Taking all these things into account both Gunning and Thomas Johnson would have to conclude that this is good technical writing The final example is a unified paragraph from a different DEC manual this time a programmer s reference manual PIREX peripheral executive a component of the UNICHANNEL 15 UC15 Software System is described in Chapters 3 and 4 of this manual PIREX is a muitiprogramming peripheral processor executive
43. these spectacular distortions most students make many less startling errors through constant deviations in tenses and pronouns and by omissions interpolations paraphrases conjectures and complete improvisations so that paragraph after paragraph reaches their minds garbled blurred altered vitiated and ungrammatical FACTORS IMPEDING COMPREHENSION Researchers in reading and writing have proved in experiment after experiment that certain factors tend to interfere with a reader s understanding of written ma terial Some of the latest findings on this subject appear below Others appear in Chapters 4 through 9 of this book Long Sentences and Long Words Rudolf Flesch Robert Gunning George Klare and Others too numerous to specify are unanimous in identifying long sentences and long words as barriers to reader understanding Gunning in his TECHNIQUE OF CLEAR WRITING implies that they waste the reader s energy so that he cannot grapple with the ideas involved Klare makes the case that long sentences and long words slow down reading and tax the reader s memory The 3 8 length of the word affects word recognition he says so the longer the word the slower the word recognition time This means the reader must invest more time and energy in learning what you are trying to say Klare also contends that long sentences place a greater burden on the reader s memory span The longer the sentence the more the reader has to r
44. too rich for comfortable digestion Incidentally one bad effect of having the knot of technical data appear at the beginning is that it obscures the main idea of the paragraph Remember that the beginning is the usual location of the topic sentence in technical writing The 1077 is the dual processor 1070 with fast execution of computing loads because of the second KI10 central processor In addition this system typically has 128K 640K bytes of core memory 690K words 4 1 million characters of RM10G drum storage a RPO3G disk system with four disk drives for a total of 41 6 million words 249 6 million characters of storage a TU40G magnetic tape system with four 120KC drives a 1000 line per minute LP10C line printer a 1200 character per minute CRIOE card reader and a DC10 or DC68A communication system capable of 128 lines In expanding to the 1077 from a smaller system the user notices increased computing power but he does not need to change his 8 10 programs or learn a new command language or operating system Comment In this three sentence paragraph the lump is located in the middle in Sentence 2 And in its effect on communica tion the lump is truly malignant Look at its size It consists of roughly 9 of the 15 lines of the paragraph And it encompasses some 13 ideas A sprawling technically rich knot of varied data it serves to interrupt the natural flow of ideas from sentence 1 to sentence 3
45. two things 1 write small programs to calculate and 2 provide a function This he gt realizes is illogical so he has to back up and read again The writer is addicted to abstract words passive constructions long words and vague words Example Sophisticated application speci fications thus might require complex data structures involving many interrelation ships Comment Sophisticated application speci fications is long abstract and vague as are the words complex and interrelationships Example Many computer languages are currently in use but BASIC is one of the simplest of these because of the small number of clearly understandable and easily learned commands that are required its easy application in solving problems and its practicality in an evolving educational environment Comment This sentence contains a handful of long abstract terms that obscure its 2 8 precise meaning clearly understandable readily learned easy application in solving problems practicality and last but by no means least evolving educational environ ment In addition the sentence is confusing at the word but At that point the reader is set for a contrast involving the idea of being in use He expects something like but when BASIC goes to the field most of them will no longer be in use The writing reveals an inner confusion of thought Example Strings can be concatenated by means of the p
46. Proceedings Colorado State University Fort Collins Colorado 1965 R 5 Institute in Technical and Industrial Communications Eleventh Annual Proceedings Colorado State University Fort Collins Colorado 1968 Johnson T P Analytical Writing Harper and Row Publishers Inc New York 1966 Klare G R Measurement of Readability Ilowa State University Press Ames Iowa 1963 Korzybski A Science and Sanity The International Non Aristotelian Library Publishing Company distributed by Institute of General Semantics Lakeville Connecticut 1933 Menzel D H Jones H M Boyd L G Writing a Tech nical Paper McGraw Hill Book Company Inc New York 1961 Morris J E Principles of Scientific and Technical Writing McGraw Hill Book Company Inc New York 1966 Mortenson C D and Sereno K K Advances in Com munication Research Harper and Row Publishers Inc New York 1973 Nelson J R Writing the Technical Report McGraw Hill Book Company Inc New York 1952 O Hayre J Gobbledygook Has Gotta Go U S Govern ment Printing Office Washington D C 1966 Peterson M S Scientific Thinking and Scientific Writing Reinhold Publishing Corporation New York 1961 Roberts P English Sentences Harcourt Brace and World Inc New York 1962 Roberts P Understanding English Harper and Brothers Publishers New York 1958 Schlesinger I M Sentence Structure and the Reading Process Moutone Company
47. TENCE COMPLEXITY Traditional grammar defines a complex sentence as one that contains an independent clause and one or more dependent clauses Thus the following sentences are properly labeled complex 1 He came when he was ready 2 He said that he would come when he was ready But this definition gives little indication of the real nature of a complex sentence For one thing it deals only with the surface appearance of the sentence For another it leaves the reader entirely out of account The complexity discussed in this chapter is what the reader encounters when he tries to extract meaning from a piece of writing In this sense complexity refers to the total number of relations he must unravel to understand a passage This definition then sees complexity as a composite of a number of factors One of these factors is of course the surface structure of the sentence for that is what the reader sees first Actually you as a writer can present the same content in a number of different surface structures But the structures differ in effectiveness that is the reader can extract information more easily from one form than from another For example both of these sentences have the same content The programmer drove his car to work The car was driven to work by the programmer who owned it The first sentence however is likely to prove more effective from the reader s viewpoint than the second 6 1 Another facto
48. a sentence contains the more complex it is And what is even more important for the communicator Coleman and Miller s experiments proved that passages with few kernels i e short sentences are more easily understood by the reader Again because the few kerneled sentences are less complex the reader does not have to work so hard to unravel their meaning SENTENCE LENGTH Sentence length is a basic measure of complexity in a piece of writing At least this is the view of George Klare and other longtime professionals in the study of reada bility And all the practical tests of readability so far devised notably Flesch s Reading Ease Formula Gunning s Fog Index and the Dale Chall Formula embody sentence length as a factor But it is not length per se that causes difficulty for as we ve just seen a simply worded sentence of 22 words can engender as much reader pain as a rambling sentence of 42 words Rather it s the number of relationships in the sentence that causes the trouble For this reason we cannot say that a 30 word sentence is always twice as hard to understand as a 15 word sentence We can say however that since relationships depend on words long sentences are usually harder to understand simply because they contain more words Further we can indict long sentences because they strain the reader s memory span his ability to recall material correctly after reading it once Thus the writing of inf
49. an use the abstract word system instead of repeating the elements listed in the preceding sentence Actually you have made system concrete in this instance by giving it precise meaning It now refers to something that can be seen in the physical world And this is the only way of communicating successfully with abstract words WHAT S WRONG WITH ABSTRACT WORDS Writing that contains a high percentage of abstract nouns reveals the following faults 1 It is difficult to understand 2 It is inefficient in transferring information from the writer s head to the reader s 3 It is difficult to memorize These findings were reported by E B Coleman and C R Miller in the READING RESEARCH QUARTERLY in 1968 In sum these educators aim the following message at the technical writer you cannot communicate suc cessfully by using a lot of abstract nouns The reason for this is clear Words high on the ladder of abstraction are vague in meaning They tend to make a passage general and indefinite Unaccompanied by con crete nouns and active verbs they cloak a passage in a smog like haze of ambiguity that hides the writers intended message Since no word even the most specific of concrete terms means the same thing to all readers the best we can say about an abstract style is that it means different things to different readers Whereas the worst we can say is that it means nothing at all to any readers Take the word freedom for e
50. any other document which may be viewed by more than one user or multiple personnel Comment What does multiple personnel mean Is it different from more than one user The reader has to reread looking for clues to the meaning Unfortunately there are no clues in the entire paragraph Example This manual describes DBMS 10 from the point of view of the Data Base Administrator and as such it is the refer ence manual for the whole system It is not though intended to be a tutorial guide for beginning Data Base Administrators or DBMS 10 users In addition it is assumed that the reader has a knowledge of the COBOL language 2 7 Comment Two stumbling points are the word beginning and the phrase in addition Beginning the minor fault should have the in front of it to prevent people from reading it as meaning starting something In addition poses another problem Since the previous fact was negative the reader is set for another negative fact when he reads in addition And when he learns it isn t negative he has to go back to verify that the mistake isn t his Example Occasionally you may want to calculate a function for example the square of a number Instead of writing a small program to calculate this function BASIC provides functions as part of the language some of which are described in Chapter 1 Comment Because the word writing modi fies BASIC the reader thinks BASIC can do
51. arket to partners in the sex act saleswise capitalwise success wise weatherwise profitwise expensewise loanwise and even bottom linewise The computer industry con tributed programwise codewise logicwise bitwise operationwise recordwise processingwise jobwise devicewise and implementationwise Given enough time 9 3 we might even come up with computing powerwise or high performance peripheral systemwise And finally there is a whole host of miscellaneous fog words we likewise call jargon For example what makes end product and end result any better than product and result Only the autocratic say so of the Humpty Dumpty writer And the word objective Is it different from goal Hardly It is just a high sounding piece of jargon borrowed perhaps from the military But when Humpty Dumpty writes of achieving our goals and objectives he gives it a private meaning he doesn t deign to pass on to the reader And what about the word area Some people write He will be working in the networks area Or He will be in charge of all software in the communications area Do those sen tences say anything more than the following 1 He will be working on networks 2 He will be in charge of all communications software The Humpty Dumpty writer would have you believe they do But don t be duped Area here is just an empty four letter word Humpty Dumpty uses it because he has no interest in communicating
52. ary technical matter Ask yourself Does my reader need to know this Consider substituting a familiar word for a technical term whenever possible But be cautious here This advice must be used sparingly and with discretion 3 Break up the lumps in lumpy paragraphs Distribute the technical details among the various sentences 8 12 4 Use at least one sentence to explain each item in a dense series of features functions advantages benefits etc 5 Consider using tables and lists instead of paragraphs to present large clumps of tech nical details Perhaps as part of the cure you should ponder Thomas Johnson s law of density to see if you can use it asa guiding principle A reader s ability to understand a paragraph is inversely proportional to the number of technical terms that are present 8 13 CHAPTER 9 CURING THE SIXTH MAJOR ILL FOGGY WORDS There s a glory for you I don t know what you mean by glory Alice said Humpty Dumpty smiled contemptuously Of course you don t till I tell you I meant there s a nice knockdown argument for you But glory doesn t mean a nice knock down argu ment Alice objected When use a word Humpty Dumpty said in rather a scornful tone it means just what I choose it to mean neither more or less Lewis Carroll THROUGH THE LOOKING GLASS Chapter 6 Humpty Dumpty is not just a p
53. at chosen for a reader with a college education Besides readability tests give ratings in terms of grade level So if your writing is to undergo a readability test you should have the grade level of the reader firmly in mind before you write If your book is targeted for the general reader Klare s statistics on the median number of years of schooling completed by American adults could help you 1940 between 8 and 9 1950 between 9 and 10 1957 between 10 and 11 1960 about 11 1970 around 12 At any rate he suggests that sometimes you may want to use U S Census data to get a better picture of the educational level of your readership Motivation Does he have a strong desire to read what you write Does he have to read it to do his work If so he s likely to have a strong motive for learning Or is he a voluntary reader likely to lay the book aside if the subject or style either bores him or forces him to expend too much effort in extracting the meaning If you re trying to attract the voluntary reader then you must use simpler language He is not looking for a challenge and won t stay around long if your book offers him one Intellectual level Is the reader smart How smart Smarter than you Smarter than the communicator in the next office Take a guess at his I Q 110 120 How do you know he s smart What does he do that indicates high intelligence Reads the clas sics Writes poetry Plays che
54. at is unfortunate for it leads readers to believe that the new ize words coined willy nilly are equally meaningful Words like moisturize parameterize and vietnamize convey no precise idea at all Another good example of this kind of jargon is the word finalize It appeared in the following sentence in a recent DEC memo We intend to finalize the project plan Thursday afternoon Does this mean 1 They intend to review the plan for the final time 2 They intend to insert all input from previous reviews 3 They intend to decide on exactly what will go into the plan and what will be excluded 4 They intend to have the plan signed by the people who must approve it 5 They intend to have it typed and ready to submit to the people who must approve it 6 They intend to submit it for final review by the people who must approve it Most of the new ize words leave the reader in this kind of quandary regarding their meaning Thus it is that jargon works its harm on communication Equally bad are the wise words Again the suffix was formerly used with precision to denote manner direction or position Thus we have serviceable terms like clockwise lengthwise widthwise and counterclockwise But largely through the efforts of the commercial writers wise came to mean with reference to And readers are flooded with the likes of taxwise pricewise performancewise which has been applied to everything from the stock m
55. ather the data on the experience and background of the reader so that you will use terms and other symbols the reader will understand You re expected to have a firm grasp of the needs of the reader so that you will know which facts to communicate You must be motivated by the desire to make the reader understand This feeling guides you in organizing the technical infor mation and in emphasizing important points You are presumed to have mastered the art of communicating making your words mean 1 5 what you want them to mean in the mind of the reader 6 You must realize that language does not have to be elegant You have to see it correctly as a tool for transferring ideas 7 You must constantly monitor your docu ments to ensure that self expression does not take the place of informative writing 8 You must remember that the deeper the subject the harder you must work to make it understandable 9 You must never lose sight of your overall goal to simplify the complex for the reader THE MEANS OF TRANSMISSION The written language of the verbal communication system is called exposition It is the link between the outside world and the ideas in your mind Since its purpose is to inform it appeals to the reader s intellect not to his feelings or imagination Ideally you should make it clear and unambiguous sending ideas by the shortest most efficient route It should always give the reader all he needs to know a
56. be added by connecting the DC7IE to the DC71D Terminals can be Teletypes VT06 8 4 or VTOS display terminals or other Tele type compatible terminal interfaces at speeds up to 2400 baud Comment Perhaps the facts in this para graph would look better in a vertical list because that is exactly what the paragraph is A list of very thinly related technical facts A long sequence of such paragraphs would be deadening to the reader In evitably they would cause the breakdown of communication The writer should do two things First he should ask whether all these technical facts are necessary That is does the reader of this manual need to know them all If the answer is yes then he should break up the paragraph into at least three smaller ones Thus he could consider the remote batch terminal the line printer and the other terminals as topics for separate paragraphs 2 Single DDI or dual DSP DOV displays are provided along with a set of display control commands Two small vertical lines known as fixed cursors DCU and two bright crosses known as free cursors DFR can be displayed Through these free cursors it is possible to draw a straight line DLI which in most cases represents a base line The display may also be expanded DEX from the data that is between the two fixed cursors The total number of data points that are displayed may be increased DIN decreased DDE raised DRA or lowered
57. bout the subject Above all you should write it on a level that the reader can understand Remember the Washington experts who didn t know how to write to the plumber THE RECEIVER The receiver of your exposition is the reader He comes to your writing to learn some technical facts That learning may be a knowledge of ideas and their relationships Or it may be a grasp of procedure knowledge of the steps to follow to do a certain task In either event communication takes place when he ex tracts from your writing the meaning you put into it that is when his interpretation of the meaning closely approaches yours Only then can he perform the procedure you wrote about or discuss the ideas you expressed However if he cannot decode your message correctly communication breaks down And poor communication is mostly a matter of interpretation Sometimes the reader responds more to the implied meanings conno tation of the words than to their literal meanings denotation Sometimes he distorts the meaning be cause the language is too difficult for him Most of the 1 6 time he goes astray because of the various kinds of noise accompanying the message NOISE In communication theory noise is any unnecessary or misleading information conveyed by your writing Like static or other interference on radio or television noise impedes communication It prevents the reader from getting the meaning intended The reader experiences n
58. ccurate determina tion unless the dialogue is appropriate And secondly appropriateness is taken for granted hasn t this software been tested DEADWOOD FACTOR Original The project plan does not consider the prohibitive cost factor Revision The project plan does not consider the prohibitive cost Original Field data proves conclusively that this monitor has a high reliability factor Revision Field data proves conclusively that this monitor has high reliability DEADWOOD ACTIVELY Original For the last two years we have been actively supporting two monitors Comment Delete actively Unless of course we passively support other monitors DEADWOOD ACTUAL Original There are three major components of the computing system the actual machine or hardware the operating system or monitor and the languages and utilities or nonresident software Comment Delete actual Machine and hardware as everyone knows exist in the actual world So the emphasis provided by actual is not needed Besides aren t operating system languages and utilities also actual Moreover nowhere in this sentence is there any contrast with something not actual 9 10 SUMMARY Words are the basic building blocks of your writing And how you pick and choose among them determines your success in getting ideas from your head to the reader s Choose words your reader understands and you can build a v
59. ccurately measuring and counting intervals or events It can be used to synchronize the central processor to external events count external events measure intervals of time between events or provide interrupts at programmable intervals It can also be used to start the analog to digital converter by means of the overflow from the clock counter or by firing a Schmitt trigger Many of these operations can be performed concurrently Comment The second sentence about how the real time clock can be used is too dense and general The writer should have devoted a sentence or two to each function The third sentence should have been expanded in the same way And all the needless mystery can be swept out of the last sentence by telling which operations can be performed concurrently 2 Lab Applications 11 modules are available to perform operator console interaction data acquisition data editing Fast Fourier transformation output printing and dis playing Lab Applications 11 allows many varieties of these functions The library of modules will be enhanced as time goes on and as application needs are defined more and more of the requirements for laboratory computing will be supplied by DIGITAL Comment The first two sentences embody a dense but general list If they are in tended to inform they should be explained If they are not intended to inform they should be eliminated At the very least the writer shou
60. ch was first published in October 1933 Korzybski a philosopher and scientist gave us many new insights into the nature of language and meaning Two of his contributions are discussed in this chapter The first deals with the relationship between language and reality The second has been popularized by his disciples as the ladder of abstraction LANGUAGE AND REALITY There is no direct connection between language and the world around us The connection is indirect through the minds of the people who use the language Because you and I agree that a particular word shall refer to a certain thing in the external world we can use that word to communicate about that thing Our agreement then is the only connection between the word and the thing And such an agreement is purely arbitrary we could just as easily have agreed that another word would stand for that thing In Figure 4 a dotted line stands for the indirect relationship between words and the external world Writer A The word dog B C The animal dog Figure 4 Indirect Connection Between Word and Thing In the diagram the writer A sees an animal C He uses the word dog B to refer to this animal This word is what users of the English language have agreed shall refer to that kind of animal If A were among people who knew only French the word dog would have no meaning A would have to know the word chien in order to communicate Similarly among Spanish
61. ciples from them These questions show that competence in writing is connected with competence in thinking In fact they cannot be separated Thus a writer can never be both skillful on the competence level of writing and fuzzy in his thinking He can however be very skillful on the literacy level of writing and very incompetent in his thinking Notice that the experts mentioned in the following sections are concerned only with competence They don t stoop to deal with literacy at all Rather they harp on clearness organization exactness relevance and effectiveness These are the marks of competence in writing GUNNING S WARNING TO TECHNICAL WRITERS About thirty years ago articles in the popular magazines were dry statements of fact backed up by cold statistics The style was consistently stiff and dull and the competence of the writing was low So readers finding them hard to read sent loud complaints to the maga zines Not only did the readers voice their dislike of the articles but they also specified what they wanted in place of them The result is the modern article which in contrast with the old is highly competent because it is highly readable The point is that magazine articles changed because the magazines themselves responded to reader dis satisfaction Invariably this is what happens when publications must depend on the reader for their existence So says Robert Gunning in his book THE TECHNIQUE OF CLEAR
62. courses with perhaps two addi tional courses in college or technical school So you know clauses and sentences and parts of speech And you either have at your fingertips the accepted rules of punctuation and usage or know where to get such information when you need it Too you are no stranger to writing you ve written letters and memos and reports But you are new to this task of writing technical manuals for a large and varied readership So you need a book of tips on how best to write for that body of readers You need a book of ideas and principles On the other hand you don t want to be burdened with rules to memorize and exercises to do If you fit this reader profile then WRITING FOR THE READER is indeed for you CHAPTER 1 TECHNICAL WRITING AS COMMUNICATION On the West Coast they tell the story of a plumber who started using hydrochloric acid on clogged pipes Though he was pleased with the results he wondered if he could be doing something wrong So he wrote to Washington to get expert advice on the matter In six weeks he received the following reply The efficacy of hydrochloric acid in the subject situation is incontrovertible but its corrosiveness is incompatible with the integrity of metallic substances The plumber who was short on formal education but long on hope was elated He shot a thank you letter back to Washington He told them he would lose no time in informing other plumbers about his di
63. d that the connected task maintains a pointer to that location in the buffer where it is to next retrieve contact interrupt data When a task is triggered by the handler it should process data in the buffer starting at the location indicated by its pointer and continuing in a circular fashion until the two pointers are equal Equality of pointers means that the connected task has retrieved all the contact interrupt information that the handler has entered into the buffer The pointer main tained by the handler is to be thought of asa FORTRAN index into the buffer i e the first location of the buffer is associated to the number index 1 The second location associated to the module number indicates a module on which a change of state in the direction of interest has been recognized for one or more discrete points Average sentence length 25 words The detection of any card reader error condition in Batch signifies a Device not Ready state which elicits a A 2 message and disables the reader interrupt If the operator issues a CONTINUE command to resume processing the error processor will recall the Transfer routine to repeat the read and exit to await the next interrupt The operator is given the opportunity to correct the error before entering the CONTINUE command The card using the error should be replaced and the replacement card should be the first card read when processing resumes An exception to this procedure
64. dangling modifiers A modifier is said to dangle when logically it has nothing in the sentence to modify For example the underlined modifiers in the following sentences are dangling 1 In packing the car his typewriter was overlooked Typewriter is packing the car Yet type writer is the only word that packing can _modify To correct the sentence change the verb to the active voice and put the logical doer in the subject spot In packing the car we overlooked his typewriter 2 To examine the television set the plug should be removed Plug is going to examine the television set But plug is the only word that to examine can modify Again part of the correction of this fault is to put the logical doer into the subject spot To examine the television set you should remove the plug 3 Flying his helicopter close to the ground the two year old wanderer was spotted in the woods A two year old wanderer is flying Once again we have a dangling modifier Flying has nothing but wanderer to modify And as before we can correct the sentence by 1 putting the verb in the active voice and 2 inserting a logical doer in the subject spot Flying his helicopter close to the ground the pilot spotted the two year old wanderer in the woods In most cases the danglers aren t really misread People smile at them and then quickly apply their own logic to extract the right meaning However when a passage contains a lot o
65. de one fact about him stand out generally he reads poorly And the larger the readership you aim to reach the greater the number of poor readers you ll meet They certainly wont admit they re poor readers Perhaps they don t even realize they are So unless you take pains to help them in the ways suggested in this chapter you ll miss them with your message Then they ll have a perfect right to scream 3 14 that your manual is garbage because the burden of communicating rests squarely on you When you stop to think about it your job is much tougher than you thought Not only must you write to be understood by the reader but considering his many reading disabilities you must also make certain you are not misunderstood 3 15 CHAPTER 4 CURING THE FIRST MAJOR ILL THE UNORGANIZED PARAGRAPH One sure way to help your reader is through strong organization of the paragraphs you write This advice is especially apt when your ideas are totally unfamiliar to him or when his background in the subject is weak In either case the tighter you make the organization the better the transfer of ideas This view has the unqualified support of prominent professionals in the field of verbal communication Two such professionals Ludwig Mosberg and Fred Shima tell of an experiment that typifies the beneficial effect of tight structure on communication Although the experiment had to do with oral rather than written discourse the findi
66. declaring sets in the schema is a responsibility of DBMS 10 To be sure there is no known way to measure required memory level But this shouldn t deter you from using it to your advantage as a communicator Accept the fact that it does indeed exist It is real because there is a limit to the temporary complexity that any human mind can adjust to Hence you can help the reader by anticipating his difficulty with sentences having too great a distance between subject and verb Revise such sentences before they get into the manual Revert to the subject verb complement word order of the declarative sentence This order not only reduces the required memory level but it also clarifies relations among the various sentence elements For example say declaratively DBMS 10 is responsible for setting and keeping up relationships between the records declared by sets in the schema Transformational grammar presents a view similar in effect to Morris required memory level Coleman and Miller who represent the transformational approach speak of kernels as the simple units of language Writers transform these kernels to make complex sentences As an example of a single kerneled sentence they offer the following They gave her a dollar On the other hand a many kerneled sentence is They admired her intelligent lectures This sentence is made up of three kernels she lectured she was intelligent and th y admired The more kernels
67. e 3 6 _The second point concerns your choice of words Choose many syllable words only if you want to run the risk of missing your reader Granted you as a writer have a perfect right to use words like inert antiseptic and hydride But if your reader is likely to read them as inherent adhesive and hydroxide what have you gained One thing is certain you ve failed to inform the reader you ve failed to communicate Anything you think you ve gained is trivial beside the failure to communicate A purely practical point shedding addi tional light on this topic comes from the experiments of E B Coleman and C R Miller They found that college sophomores learned the most from instructional ma terials written on the fifth grade level Moral to communicate the most use small words and short sentences One thing we know with absolute certainty about readers is that they all get a somewhat different meaning from a piece of writing This is so partly because each one judges your words by his own unique experience Moreover they adapt your words to their own expecta tions limitations and ignorance To illustrate this truth Helen Lowe tells the story of the student who con stantly read elephant house for elephant cage The writer made a mistake she said when asked for an explanation elephants live in houses not cages Another one con tinually read supper for dinner because people eat supper at night not dinner It would i
68. e connection between processor and peripheral devices DEADWOOD PARTICULAR Original This software allows him to define the hardware configuration of his particular installation Comment Delete particular As in the preceding example the possessive his serves to designate the installation Particular just repeats needlessly DEADWOOD EXISTING Original Existing programs and data files can be modified directly with BASIC instead of with a system editor by adding or deleting lines by renaming the file or by resequencing the line numbers Comment Delete existing Since modifying non existing programs and data files would appear to be an impossibility the use of existing is needless However when there is a kind of contrast between the existing and the nonexisting the use of the word existing is valid For example the following usage from the same manual is all right Com mands to LINED allow the user to create a new file or edit an existing file DEADWOOD APPROPRIATE Original This program determines by appro priate dialogue with the user who he is whether or not he is currently authorized to use the system 9 9 and if so establishes the user s initial profile informs him of any messages of the day and reports any errors detected in his disk files Comment Delete appropriate Of course the dialogue is appropriate for two reasons First the program cannot make an a
69. e is The coding she did but the documentation she refused to do Von Glasersfeld labels such sentences prospective am biguity They make for greater difficulty than normal sentences he says because two or more different interpretations have to be made and kept in temporary storage during processing of the sentence Since they do indeed cause greater reading difficulty the writer should question whether the reader can derive enough benefit to warrant their use Of course the sentence structure in the example appears infrequently in technical writing But the same cannot be said of the conditional clause without the word if It appears often and has just as much prospective am biguity as von Glasersfeld s example Here is one such sentence from a DEC manual Should the Data Base Administrator or any user suspect that a privacy key has become public knowledge the Data Base Administrator should immediately issue a new unique lock key com bination to replace the one in question At the word should the reader must be prepared for 1 a question or 2 a conditional clause And he must keep these alternatives in mind until he reaches the word that Truly the conditional without if especially if the clause is long serves to burden the poor reader Position of Information in a Paragraph Does the position of information in a paragraph influ ence a reader s ability to remember it The answe
70. e of Education Document Number ED 091749 1972 Brewer R K The Effect of Syntactic Complexity on Readability Dissertation for Doctor of Philo sophy Degree University of Wisconsin 1972 Clapp E R Why the Devil Don t you Teach Freshman to Write Saturday Review Volume 48 pages 63 93 1965 Coke E J Readability and Its Effects on Reading Rate Subjective Judgments of Comprehensibility and Comprehension Educational Resources Informa tion Center U S Office of Education Document Number ED 074152 1973 Coleman E B The Comprehensibility of Several Gram matical Transformations Journal of Applied Psychology Volume 48 pages 186 190 1964 Coleman E B Learning of Prose Written in Four Grammatical Transformations Journal of Applied Psychology Volume 49 pages 332 341 1965 Coleman E B and Miller C R A Measure of Infor mation Gained During Prose Learning Reading Research Quarterly Volume 3 pages 369 386 1968 Coleman E B and Miller C R A Set of Thirty six Prose Passages Calibrated for Complexity Journal of Verbal Learning and Verbal Behavior Volume 6 pages 851 854 1967 Dansereau D F Analysis of the Reading Comprehen sion Process The Development and Utilization of an Assessment Technique and the Preliminary Exploration of Individual Differences in Perceiving Syntactic Complexities Educational Resources Information Center U S Office of Ed
71. ehicle to carry your ideas to him Choose jargon big words and deadwood however and you build a barrier to stop your ideas in their tracks For nothing can improve a passage whose words do not inform not unity not coherence not the active voice not any of the principles discussed earlier in this book So do your reader a favor pick building blocks that help him understand Don t be another Humpty Dumpty REFERENCES ARTICLES DISSERTATIONS AND MONOGRAPHS Adams E B A Comparison of Two Techniques of Presenting Information in a Public Information Bulletin Dissertation for Doctor of Education Degree University of Wyoming 1972 Backus M G Conservation and Reading Comprehen sion Educational Resources Information Center U S Office of Education Document Number ED 094365 1974 Bloomer R H Level of Abstraction as a Function of Modifier Load Journal of Educational Research Volume 52 pages 269 272 1959 Borgh Enola Transformations and Stylistic Options Educational Resources Information Center U S Office of Education Document Number ED 078445 1972 Bormuth J R Development of Standards of Reada bility Toward a Rational Criterion of Passage Performance Educational Resources Information Center U S Office of Education Document Number ED 054233 1971 Botel M and Granowsky A Syntactic Complexity Formula Educational Resources Information Center U S Offic
72. emember till he gets to the end of it But the most telling indictment of long sentences and long words comes from a scholar of the 19th century Herbert Spencer In his PHILOSOPHY OF STYLE appears the following passage A reader or listener has at each moment but a limited amount of mental power available To recognize and interpret the symbols presented to him requires part of this power to arrange and combine the images suggested requires a further part and only that part which remains can be used for realizing the thought conveyed Hence the more time and attention it takes to achieve and understand each sentence the less time and attention can be given to the contained idea and less vividly will that idea be conceived Sentence Structure Your sentence structure may serve to burden the poor reader We will say more about this in Chapter 6 but here we want to relate some interesting observations by Ernst von Glasersfeld He points out that a lot of split second internal processing takes place when the reader sees a sentence that begins with the words The coding she did At this point the reader has to pull two possible interpretations into temporary mental storage One of them is that the structure is a relative clause equal to The coding that she did in case the sentence is The coding she did was praised by her supervisor The other interpretation is that the structure is inverted in case the sentenc
73. en speaking of memory locations it is very important that a clear distinction is made between the address of a location and the contents of that location A memory reference instruction refers to 4 7 a location by a 12 bit address however the instruction causes the computer to take some specified action with the content of the location Thus although the address of a specific location in memory remains the same the content of the location is subject to change Jn summary a memory reference instruction uses a 12 bit address value to refer to a memory location and it operates on the 12 bit binary number stored in the refer enced memory location There is no joint trouble in this excerpt In the four sentences the writer guides the reader with seven of the words and expressions in Table 1 He uses when to denote time however and although to show contrast between ideas thus to indicate a cause and effect relationship and in two instances to show equality of ideas and in summary to signal the reader that a summary of the paragraph is coming his way All these things considered the paragraph is a good example of coherence in writing Another model of effective coherence in DEC software writing is as follows Writing the above program was greatly simplified because mnemonic codes were used for the octal NwuINv AY reston Anwin tha hanlbheta instructions Ho WUE waung UvVyval uit a050i1ucc address of each inst
74. encouraged by Robert Gunning s observa tion Nearly any subject can be discussed in prose that does not go beyond mid high school level in complexity CHAPTER 7 CURING THE FOURTH MAJOR ILL OVERUSE OF THE PASSIVE VOICE Many experts on writing aim their heaviest verbal artillery at the use of the passive voice Morris Freed man for example calls it the deadly passive and labels it Sin Number 6 in his famous article Seven Sins of Technical Writing He asserts that it makes any reading matter more difficult to understand to get through and to retain In a similar vein Herman Struck writing in the SCIENTIFIC MONTHLY advises A writer might well consider every passive sick until he proves it healthy This chapter also takes issue with the passive voice But as the title clearly indicates overuse not use is the ill that needs treatment In other words we do not condemn the passive voice per se It can and should be used to good effect in technical writing where the emphasis is more often on the thing rather than on the person What we do condemn however is the technical writers needlessly heavy dependence on it This we submit is what helps give technical writing the dead liness that Freedman detects a lack of emphasis vitality and motion This chapter discusses 1 identification of the passive voice 2 the case against the passive 3 the case for the passive 4 the
75. ensest fog of all Then the reader is hit with clusters of meanings And there is no telling what message he goes away with Moreover combinations of big words usually add up to long sentences And long sentences as the experts assert are the greatest barrier to efficient communication Three examples from DEC software documentation show how combinations of big words make the meaning unclear Too they show how word bigness and sentence length go hand in hand 1 Example The KI10 processor provides measures for handling arithmetic overflow and underflow conditions pushdown list overflow conditions and page failure con ditions directly by the execution of pro grammed trap instructions instead of re sorting to a program interrupt system 36 words Comment Measures three uses of condi tions and resorting to spread a meaning concealing haze over the main idea in this sentence Example With the increased memory size the high performance peripheral systems and the large file system the 1070 is configured for maximum support of remote batch capabilities through the synchronous communication equipment 31 words Comment Again such mouth filling terms as high performance configured maximum support and capabilities serve to hide the writer s thoughts Example This approach of co equal proc essors gives the user increased computing capacity when processing power is in heavy demand under mul
76. er You should use what you need That s the spirit in which they are given as principles to guide your imagination rather than as rigid rules to hamper it ANOTHER READER PROFILE You can further sharpen your reader image with facts about readers in general about how poorly they read and how inefficiently they process information To be sure it s a universal truth that all readers read differ ently But some of the facts supporting that truth show readers to be much less proficient than even the most pessimistic views have them 3 4 For instance in 1970 J R Bormuth of the Department of Education at the University of Chicago wrote a monograph entitled Illiteracy in the Suburbs In it he asserted 1 That 51 of the students graduating from American middle class suburban high schools cannot read and understand the textbooks in their classes and _ 2 That 41 cannot read and understand ordi nary newspapers and magazines Before looking at the implications of these statements we want to emphasize two facts Mr Bormuth is no sensation seeking newspaperman He is a highly re spected educator a painstaking researcher and a re nowned interpreter of facts Secondly he has limited his observations to middle class suburban high schools where the quality of education has usually been con sidered better than in the teeming cities In other words he s talking about the so called better schools If he had
77. er of 1 to 5 digits that serves to identify the line as a statement A program is made up of statements Line numbers serve to specify the order in which these statements are to be per formed Before the program is run BASIC sorts out and edits the program putting the statements into the orders specified by their line numbers thus the program statements can be typed in any order as long as each statement is prefixed with a line number indicating its proper sequence in the 4 12 order of execution Each statement starts after its line number with an English word which denotes the type of statement Unlike statements com mands are not preceded by line numbers and are executed immediately after they are typed in Refer to Chapter 9 for a further description of commands Spaces and tabs have no significance in BASIC programs or commands except in messages which are printed out as in line 65 above Thus spaces and tabs may but need not be used to modify a program and make it more readable The writer attempted feebly with these and thus and unlike to connect parts of the paragraph But his connectives were too few and too weak to alter the net reader impression that the paragraph is unorganized Clearly his main trouble is that he started out in the haystack style and couldn t shake it entirely later on Notice for instance that his first three sentences contain a catalog or list of unconnected facts This fault late
78. er transformation output printing and displaying Lab Applica tions 1 1 allows many variations of these functions The library of modules will be enhanced as time goes on and as application needs are defined more and more of the requirements for laboratory computing will be supplied by DIGITAL Only one connective is used in the whole paragraph That s the word these in the second sentence and it serves to identify ideas not to indicate any logical relationship among them Replace these with the and you can shuffle and rearrange these sentences and still retain the same effect or lack of it Again there is no indication of relative importance or of what all these facts mean to the individual reader or even why they are assembled in this paragraph at this time And as in the previous paragraph the reader must assume the whole burden of interpreting the data a task no reader of exposition should ever have to undertake The next example is more frustrating to the reader because the logical relationships are implied but not explicitly shown As these data bases increase both in use and sophistication their creation and management must be relinquished by individual application programmers in favor of greater coordination and centralized control It has become too costly and or impractical in most instances for indi vidual programmers to create data bases for single applications on a one to one basis The need at
79. eral 5 2 many syllable 3 7 picturable 5 6 5 9 recognition of 3 9 small 3 14 transitional 4 4 l vague empty and difficult 1 7 Writer chief concern of 2 5 26 ordered thinking of 4 8 purpose of 2 6 right attitude of 2 5 style of 1 7 wrong attitude of 2 3 Writer reader contract 3 12 4 2 4 5 4 6 Writing bad habits of 2 4 complex 2 4 confusion of thought in 2 9 four step approach to 2 5 goal of 2 4 reading it aloud 2 5 tone of 3 3 unorganized 4 10 Writing to be understood 3 15 Writing to impress 2 4 Index 9 d V VGYMxX 00 03a tn e 7 5 T a
80. erely a verbal reflection of the linkage among the ideas in the writer s mind Coherence in this sense is like thought itself It has the lively onward motion of thought as it carries the reader through the material Thus coherence is vitally connected with the competence level in writing You can be effective in getting your ideas into the reader s head only when you show him how they are connected And how does the writer show such connections In other words what are the transitions i e words and expressions you can use to guide the reader The simplest transitions of course are pronouns and the repetition of keywords from preceding sentences These are basic connectives that tie facts together but con tribute little to the flow of ideas They have value because by indicating identity or sameness of ideas they keep the reader oriented But they are of secondary value in that they fail to show the reader the kind and order of your ideas For the latter aim you need the words and expressions listed in Table 1 As a quick test why don t you go through a couple of pages of your own writing and underline any words appearing in Table 1 If you don t find them often enough then you are not tying your ideas together logically and naturally And your sentences in the words of Jacques Barzun and Henry Graff are weak at the joints Similarly let s test the joints of some examples from DEC software manuals Wh
81. erlined Revision When this option is assembled in the module GITRCAL and DISSKP combine to determine what is to be done to the display file Active verb is underlined Watch the proportion of passive verbs in your writing Robert Gunning says that the proper balance for effective communication is one passive to every 9 active verbs This seems rather lopsided for technical writing where 3 to 9 throughout a manual would appear more reasonable 7 16 CHAPTER 8 CURING THE FIFTH MAJOR ILL FAST PACING AND DENSITY The scene is the corner of Boylston and Tremont Streets in Boston A new visitor to the city stands before the entrance to the MBTA subway He wants to go to Copley Square to get a close up view of the architecture of Trinity Church the Boston Public Library and the Old South Church Above the entrance to the subway he sees a solitary sign INBOUND TRAINS ONLY From his position he can see another subway entrance across the street This one is likewise labeled with a single sign OUTBOUND TRAINS ONLY Which way to Copley Square Is Copley in or out The signs fail to enlighten him To answer the question he must cither ask one of the Bostonians whizzing past him or descend the 50 odd steps into the subway to ask the person in the change booth These two signs are examples of what is called fast pacing in writing reliance on a few words to convey a lot of meaning Fast paced writing is terse
82. essage 1 6 Denotation literal meanings 1 6 Density 2 11 8 1 adjective strings 8 3 lumpy paragraphs 8 9 stuffed paragraphs 8 4 unexplained series 8 8 Descending the abstraction ladder 5 3 Directness natural 2 4 Doer of the action 7 2 7 3 7 13 Index 2 INDEX Cont Effective coherence 4 8 Effective communication 1 4 Effectiveness 2 2 Emphasis lack of 4 11 Equal ideas 2 9 Equality and subordination of ideas 2 2 Exactness 2 2 Exposition 1 6 4 11 5 8 Exposition changes in logical order of 3 12 Facts catalog of 4 10 4 13 Facts grammatically equal 4 11 Flesch Rudolf 3 8 5 11 5 13 6 7 Flow of thought in written material 4 7 Foggy words 9 2 9 3 9 6 big words 9 5 deadwood 9 1 9 6 jargon 9 1 Freedman Morris 5 8 7 1 7 10 General concrete words 5 5 Generality level 5 3 54 Graff Henry 2 7 4 7 5 11 5 12 Grammar 2 1 reader s 3 7 writer s 3 7 Grammatical equality of facts 4 11 Granowsky Alvin 7 5 Gulf between writers and readers 2 3 Gunning Robert 2 2 3 8 3 14 4 3 5 5 5 8 5 11 5 12 6 11 7 4 Gunning s warning 2 2 Hard words 2 3 Haystack paragraph 4 10 Hicks Tyler 3 4 Holmes V M 3 11 3 13 Houp Kenneth 6 7 Humpty Dumpty writer 9 4 Ideas connected 4 7 equality of 2 2 2 9 foggy 9 2 identity of 4 7 4 11 Index 3 INDEX Cont kind and order of 2 1 2 2 4 7 natural flow of 8 12 Illiterate graduates 3 6 I
83. executed by the PDP 11 It is designed to accept any number of requests from programs on the PDP 15 or PDP 11 and process them on a priority basis while processing other tasks concur rently e g spooling other I O requests PIREX services all input output requests from the PDP 15 in parallel on a controlled priority basis Requests to busy routines tasks are automatically entered queued onto a waiting list and processed when ever the task in reference is free In a background environment PIREX is also capable of supporting up to four priority driven software tasks initiated by the PDP 15 or the PDP 11 The one defect in this paragraph is slight for a moment the reader is in doubt as to the topic of the paragraph It could be a thumbnail sketch of PIREX or a short overview of Chapters 3 and 4 The first word in Sentence 2 however resolves the doubt Again as in the previous paragraphs the writer makes a contract and abides by it But sometimes we break faith with the reader Look at the following paragraph for example A computer like any other machine is used because it does certain tasks better and more efficiently than humans Specifically it can receive more information and process it faster than a human Often this speed means that weeks or months of pencil and paper work can be replaced 4 4 by a method requiring only minutes of computer time Therefore computers are used when the time saved by using a co
84. f them the reader has to slow his pace needlessly Consequently he could become bored with the book and put it aside And there is always the possibility that a dangling modifier may convey erro neous perhaps disastrous information 7 6 Our documentation with its emphasis on the use of the passive voice contains many danglers Here are a few examples 1 By dividing the DBS files into pages and storing selected records on these pages and using a page as the basic I O buffer size DBCS operations that affect the records on only one page can be handled with a single disk access DBCS operations is dividing storing and using 2 To clarify this the concept of public disks and private disks must be explained The concept is clarifying this If so why must it be explained 3 In describing each of these statements a line number is assumed and brackets are used to denote a general type Line numbers and brackets are describing the statements 4 To indicate that a statement is to be continued the line is terminated with the LINE FEED key instead of the RETURN key The line is doing the indicating Why not the user 5 This statement is used when writing a program to process data to be supplied while the program is running Who is writing a program Not statement 6 Before considering data access several as pects of data organization should be discussed
85. fuzzy or misleading to the reader What s even worse he s writing prose only he under stands Michaelson pointed to a similar danger on the part of the reader Most of the time he said the reader does not see the words as ambiguous He just interprets them according to his own understanding and experi ence and then goes on his way This kind of faulty communication where the minds of the reader and the writer meet only through the wildest of coincidences can easily result in accidents with equipment loss of sales and of good will and quite possibly lawsuits Our own documentation has many examples of the use of abstract terms whose meaning the reader is allowed to supply as he wishes At least the writer seems to have failed to give a meaning for him In this vacuum the readers mind will provide a meaning from his own experience Here are a few of those examples from DEC software documentation 1 Example VERIFY provides the user with a facility for verifying the consistency and validity of a file structure on a specified device 58 Comment Facility consistency and valid ity are high on the ladder of abstraction Notice that they can be neither sensed nor pictured Nor are they readily seen in the physical world Such words are likely to leave the writer and reader poles apart regarding their meaning Example Therefore while the scientist designs experiments or tests from content area princip
86. g principle No reader should ever have to analyze one of your sentences in order to understand it 2 When you have to write a long sentence put the predicate close to the subject 3 Break compound sentences in two once in awhile And then begin the second sentence with and but or for 4 See if you can use a period where you d be inclined to use a comma or a which 5 Count the words in any long sentence If there are more than 21 consider revising it 6 10 Use balanced or parallel phrasing to make long sentences more understandable Con sider that this 73 word sentence from Lincoln s Second Inaugural Address is under standable because of its balance or symmetry With malice toward none with charity for all with firmness in the right as God gives us to see the right let us strive on to finish the work we are in to bind up the nation s wounds to care for him who shall have borne the battle and for his widow and orphan to do all which may achieve and cherish a just and lasting peace among ourselves and with all nations The balance in that sentence is seen in the three phrases starting with the preposition with and the three infinitive phrases to bind up to care to do Imitate the natural structure of speech One result is that your subjects and verbs will be close together Constantly ask yourself this question when you revise Can I write this sentence more briefly and clearly Be
87. general But another author singles out the technical writer for his part in creating the gulf In ANALYTICAL WRITING Thomas Johnson calls the technical writer to task for 1 lack of organization 2 impersonal style 3 use of big words and 4 reluctance to state an idea directly WRONG ATTITUDE Johnson implies that the writer creates the gulf delib erately A better explanation blames the writer s attitude his view of the writing task As you will see later Gunning supports this view The new writer according to the better explanation is apt to have a wrong attitude toward writing Talking about technical matters involves him in no difficulty at 2 3 all In the role of speaker he is usually logical and straightforward But when he sits down to write he changes He is not himself His natural directness disappears he becomes stiff and formal and striking a pose proceeds to erect a wall of artificiality between himself and the reader Whereas in speaking he would say You must learn the operating system before you start working as a data base administrator In writing it becomes Familiarity with the operating system must be acquired prior to attempting the undertaking of the role of Data Base Administrator DEC Manual What transforms a clear speaker into a murky writer The experts offer a number of reasons Robert Gunning for one has strong feelings about the matter Many writers wh
88. ginal A READ statement is used to assign to the listed variables those values which are obtained from a DATA state ment 20 words Revision A READ statement assigns to listed variables the values obtained from a DATA statement 14 words Saving From 20 words to 14 A saving of 6 words 2 Original The value assigned to a variable does not change until the next time a LET 738 INPUT or READ statement is encountered that contains a new value for that variable or when the variable is incremented by a FOR statement 39 words Revision The value assigned to a variable does not change until another LET INPUT or READ statement assigns a new value to that variable or until a FOR statement increments the variable 31 words Saving From 39 words to 31 A saving of 8 words 3 Original TABS like spaces are used to make a program easy to read 12 words Revision TABS like spaces make a pro gram easy to read 9 words Saving From 12 words to 9 A saving of 3 words Original An expression is a group of symbols which can be evaluated by BASIC 13 words Revision An expression is a group of symbols BASIC can evaluate 10 words Saving From 13 words to 10 A saving of 3 words Original The exclamation mark is nor mally used to terminate the executable part of a line and begin the comment part of a line 22 words Revision The exclamation mark n
89. he result will at least be a unified paragraph The final paragraph comes from a different manual The text Editor EDIT is used to create and modify ASCII source files so that these files can be used as input to other system programs such as the assembler or BASIC Controlled by user com mands from the keyboard EDIT reads ASCII files from a storage device makes specified changes and writes ASCII files to a storage device or lists them on the line printer or console terminal EDIT allows efficient use of VT 11 display hardware if this is part of the system configuration The breach of contract appears in the last sentence in this paragraph There the writer introduces the effi cient use of VT 11 display hardware as a topic to compete with the one in the first sentence COHERENCE A less elementary way of organizing paragraphs to help the reader is by means of coherence or continuity Coherence from one point of view refers to the smooth connection between the sentences in a paragraph It is the flow or movement from sentence to sentence which the reader senses as an ease in passing from one thing to 4 6 another To the reader the sentences are tightly linked rather than loosely associated He is therefore likely to describe such writing as easy to read or easy to follow Looked at from another point of view coherence refers to the smooth flow of thought in written material Seen as such it is m
90. impress the reader then in the interest of competence you must change 3 Put your voice in your writing This is Gunning s famous dictum He says that when you talk you use your own voice which is as uniquely you as your finger prints When you write however you forget your voice with the result that your writing is not you Competent writing he says has voice in it if you know the writer you can easily imagine him speaking to you as you read his writing 4 Copy the good points of conversational style Use short sentences and short words Divide ideas into small pieces and give the reader one or two pieces per sentence Avoid inverted sentences Here is an example of an inverted structure that does not normally appear in conversation Sure he was that it wouldnt happen You will be more effec tive if you change it to the normal subject verb complement format of conversation He was sure that it wouldnt happen 5 Use a 4 step approach to writing in order to retain voice and clarify thought First write as quickly as possible as the ideas come to you Don t revise at all at this point Second analyze your written expres sion to uncover errors or gaps in your thinking Third revise what you have written to make it correct clear and exact Finally read it aloud to yourself to make sure your voice is in it Note that these suggestions help you to acquire com petence in writing The
91. ld expand on the statement about many variations of these functions The sentence is opaque as it stands Lumpy Paragraphs The term lumpy is applied to paragraphs containing an uneven distribution of technical detail Some sen tences in a lumpy paragraph are rich in technical content others contain little or no technical matter The net result of page after page of such paragraphs is to keep the reader continually off balance The following examples from one of our software manuals show that the technical lump can appear anywhere in the paragraph The 1040 is the smallest of the five systems The typical configuration of this system has a KA10 central processor 32 to 64K high speed ME10 core memories the RPO2G disk system with up to two disk packs the TM10G magnetic tape system with up to two drives and low speed periph eral equipment including a CRIOF card reader an LPIOA line printer and local DC10 lines This is an excellent system for the scientific research lab where multiple real time tasks and general computing are required and also for small colleges where there is a need for handling administrative student and faculty workloads simul taneously The system is easily expandable with most equipment on the DECsystem 10 Equipment List Comment In this instance the lump appears at the beginning Sentence 2 con tains all the technical fare of the paragraph And as you can see the fare is
92. le in his manual And what can we say about the word funds Surely the writer could have stepped down the abstraction ladder and used the word money It s more exact and more picturable MAKING ABSTRACT SENTENCES MORE MEANINGFUL What can I do to improve an abstract style you may ask The experts specifically Rudolf Flesch Robert Gunning Jacques Barzun Henry Graff Thomas John son E B Coleman and C R Miller offer a number of When you are writing on a very high level of abstraction you can communicate more effectively according to Flesch by adding 5 11 restatements on a more concrete level This corresponds to the use of illustrations practical applications examples parables and the like in teaching In a word Flesch advises you to back up abstract writing with concrete illustrations It is interesting to consider why the readers of technical manuals constantly clamor for more illustrations Is it because the concrete examples make the abstract text more understandable Gunning says you should always be aware of the position of your words on the ladder of abstraction Make certain that the terms you use actually have a connection at the ladder s bottom to observable facts Remember the loose generality of the phrase integration of software hardware and theory If you are prone to write like that ask yourself What do these words refer to in _the physical world If the answer
93. les of him created from the findings of many experts in the fields of reading and writing As far as we know this is the first time such information has been assembled in a book for writers Most of it is scattered among some 20 research projects conducted under the auspices of the U S Office of Education ONE READER PROFILE George Klare longtime reading researcher and author of the book MEASUREMENT OF READABILITY strongly urges the writer to construct a detailed profile of the reader Here are questions that Klare says can help you form this detailed reader image 1 Previous experience What is the reader s previous experience with the subject Be specific Mark it down in years and depth of knowledge Indicate depth of knowledge by showing exactly what he can do Say that he can program in COBOL FORTRAN and SNOBOL rather than say that he has been a 3 1 programmer for 4 years Is it educational or work experience Or a combination Spell it out in kind and years Does he understand technical terms or must you simplify them for him Remember that material difficult for the general reader may be perfectly understandable by a person with a spe cialized background Educational level What was the last grade completed in school This is crucial because a high correlation exists between grade completed and the individual s reading level Thus the language chosen for a high school graduate would ordinarily be simpler than th
94. les of his discipline DIGITAL has designed implementation conventions processes and functions from computer principles The processes and functions are the software elements of Lab Applications 11 This manual as well as the whole nature of Lab Applications 11 is a set of system conventions or framework used in imple menting applications This generalized sys tem design structure allows the user to create data handling systems which reflect experience the user personally may not have had time to acquire Comment This entire paragraph is on a very high level of abstraction How much of the writers meaning is actually communi cated can be known only by a quiz of both the writer and a typical reader Certainly ambiguity and emptiness appear in words and phrases on every line For example does content area principles have an exact mean ing How about such abstractions as imple mentation conventions processes computer principles nature system conventions framework applications generalized system design structures systems and experience Because of such abstract words and expres sions trying to pin down the meanings of words in this paragraph is like trying to put uniforms on a squad of ghosts Example Many computer languages are currently in use but BASIC is one of the simplest of these because of the small number of clearly understandable and readily learned commands that are required its easy applicatio
95. lus sign operator The plus sign can be used to concatenate string formulas wherever a string formula is legal with the exception that information cannot be stored by means of LET or CHANGE statements in concatenated string variables Comment The exception talks about the storage of string variables whereas the main assertion talks about the use of the plus sign to concatenate string variables The excep tion is irrelevant Example BASIC is a problem solving lan guage that is easy to learn and conver sational and has wide application in the scientific business and educational communities Comment The language says that these ideas easy to learn and conversational and wide application in the scientific business and educational communities are equal Actually in thought they should be related as cause and effect The sentence should begin with because or one of its synonyms A minor defect is seen in the words easy to learn and conversational The phrase is choppy and lacking in rhythm It serves to disconcert the reader momentarily How ever if the writer puts the word conver sational first he can make that phrase flow 2 9 for the reader conversational and easy to learn Example This software provides features which allow more than one run unit to concurrently retrieve the data in the data base even while one run unit is updating it Comment Although this
96. lways has two parts a some form of the verb be e g is am are was were has been have been had been etc and b the past participle of another verb Usually the past participle ends in ed as is the case in sentences 2 3 4 and 5 Sometimes however it doesn t end in ed as in Sentence 1 The line of action in the passive sentence is backward the reverse of what it is in thought or actuality This is why readers find passive sentences more difficult to understand than active sentences they must search out the doer of the action Movement eo Receiver of Action Verb Doer of Action 4 Since the subject spot is the emphatic spot emphasis in passive sentences is on the receiver of the action THE CASE AGAINST THE PASSIVE The experts indict the passive voice on the following eight counts Weakness Robert Gunning and Thomas Johnson use such words as inert motionless inactive and dull to describe verbs in the passive voice And when you consider the role of the verb in the sentence you can readily see their point The verb is usually thought of as the power house of the sentence the focus of action energy vitality and movement So widespread is this thinking that to speak of a passive verb sounds like a conflict of terms In fact most people if given the word verb in a free association test would doubtless respond with action words like run or push or climb or attack Rarely would
97. mage of reader 3 1 Impressing the reader 1 2 Increasing comprehension 3 13 Information position in paragraph 3 10 Information processing 3 4 6 2 Instructional manuals 3 11 Inverted sentences 2 5 Jones H M 7 15 Jargon 9 1 Johnson Thomas 2 3 2 10 4 4 5 8 5 11 5 13 7 4 7 10 7 14 8 13 Joint trouble 4 8 Klare George 2 6 3 1 3 7 3 8 3 9 3 14 6 6 8 12 Korzybski Alfred 5 1 Ladder of abstraction 5 3 5 5 5 6 5 9 5 12 Language simpler 3 2 Language and reality 5 1 Language as a tool 1 6 Learning motive for 3 2 Literacy level 2 1 2 4 Literal meanings denotation 1 6 Links 3 13 Logical connections 4 11 4 12 Logical order 3 12 3 13 Logical shorthand 5 6 Long paragraphs 3 14 Long sentences 3 8 3 9 6 10 9 5 Long words 2 8 3 8 3 9 Lowe Helen R 3 6 3 8 McMahon L 3 11 Main idea of paragraph 2 10 Making abstract sentences more meaningful 5 11 Manuals instructional 3 11 tutorial 3 11 Meaning four forms of 1 3 implied 1 6 multiple 1 4 Index 4 INDEX Cont Meanings 5 7 5 8 5 9 9 3 9 4 Means of transmission 1 3 1 6 Median number of years of schooling 3 2 Memory level required 6 3 Menzel D H 7 15 Meyer Bonnie 3 10 Michaelson Herbert 3 3 5 8 Miller C R 3 7 5 7 5 11 5 12 6 6 Morris Jackson 6 3 6 5 Mosberg Ludwig 4 1 Motion 4 1 Noise 1 3 1 7 origin of 1 7 Object complements 3 13 Order logical 3
98. mples are round in shape the month of February five miles in distance and the year 1620 Like dead branches on a tree these repetitions in shape the month of in distance and the year are not essential and must be pruned In larger perspective deadwood refers to 1 long expres sions that a single word can replace and 2 single words that add no meaning to a passage As an example of an overlong expression consider by the use of Three of the words are freeloaders doing absolutely nothing to carry the burden of meaning Eliminate them and you re left with by as the effective substitute for the entire phrase Similarly other sentence lengthening phrases can be reduced to a solitary word Deadwood Single Word Replacement at the rate of at by means of by for a period of for for the purpose of for in an area where where in an effort to to in order to to in such a manner as to to in terms of in involves the use of uses is designed to be is it is clear that clearly it is evident that evidently with the aid of with On the other hand an excellent example of a single word that often does nothing to further the meaning of a sentence is the word nature It is for instance needless in the following context The specifications are highly technical in nature Thus with the deadwood pruned the sentence becomes The specifications are highly technical Notice that the sentence becomes smaller
99. mplifying writing for the reader 2 5 Slobin Dan 7 5 Smith K 3 11 Source the 1 3 1 4 1 5 Speaker clear 2 4 Specific concrete words 5 5 5 6 Spencer Herbert 3 9 Struck Herman 7 1 Structural cues in written material 3 8 Structural paragraphs 3 14 Structure inverted 3 9 Structure of speech 6 11 Style impersonal 2 3 Subject complements 3 13 Syntax false cues of 2 7 Tables quick reference 3 3 Technical writer function of 1 2 unique skill of 1 2 use of the term 1 2 Technical writing essential function of 2 12 more readable 2 3 2 12 six major ills of 1 7 Terms familiar to the reader 3 3 Testing and measurement 2 1 Thinking complex 2 4 Tone of writing 3 3 Topic shifts of 4 5 Topic of paragraph 4 2 Topic sentences 3 10 4 2 Transformation grammar 6 5 Transitions 3 13 4 4 4 7 4 9 8 6 8 12 Tutorial manuals 3 11 Unity 4 1 4 2 4 3 4 4 8 7 Unorganized paragraphs 4 1 4 13 Usage 2 1 van Rooy Lois 3 11 5 6 Verbal communication system 1 3 3 1 Index 8 INDEX Cont Verb nominalization 5 12 Verbs active 5 12 7 1 7 2 occurrence of main 3 13 passive 7 1 7 2 Voice in grammar 7 1 Voice in your writing 2 5 von Glasersfeld Ernst 3 10 Weakness at the joints 4 7 Word and referent 5 2 5 3 Word order of the declarative sentence 6 5 Words abstract 5 1 5 5 as shorthand terms 5 2 big 3 7 9 1 concrete 5 5 5 6 fuzzy 5 13 gen
100. mputer offsets its cost Further because of its capacity to handle large volumes of data in a very short time a computer may be the only means of resolving problems where time is of the essence Because of the advantages of high speed and high capacity computers are being used more and more in business industry and research Most computer applications can be classified as either business uses which usually rely upon the computer s capacity to store and quickly retrieve large amounts of information or scientific uses which require accuracy and speed in performing mathe matical calculations Both of these are performed on general purpose computers Some examples of computer applications are given below Analysis of this paragraph shows that the writer prom ised in the topic sentence to talk about how a computer does certain tasks better and more efficiently than humans That s his contract with the reader and in the second and third sentences he lives up to his obligation Sentence 4 however breaks the contract It talks about computer use in relation to cost The next sentence moves to still another topic computer use in business industry and research A wholly new topic computer applications confronts us in the last three sentences These needless shifts of topic destroy the unity of the paragraph and disturb the reader They also interfere with reader comprehension As a test of this last statement reread
101. n in solving problems and its practicality in an evolving educational environment Comment Here again the meaning is elusive and constantly changing because of the abstractions the reader has to pour meaning into Look for example at appli cation problems and practicality All three are vague and ambiguous But for abstrac tions that mean little to anybody consider evolving educational environment and clearly understandable and readily learned commands Commands of course is a technical term but the qualifiers disturb its set technical meaning Understandable to whom What s the difference between understandable and learned in this phrase Are the commands readily learned be cause they are clearly understandable Example DOS BATCH has been designed to manage resources efficiently and to be easy to use It is suitable both for regular production work and by reason of its data storage facilities and debugging aids for program development However while it provides a response time fast enough for most requirements it is not intended for use in On line real time data acquisition ap plications Comment In this paragraph you ll find a number of abstract words people think have meaning because they ve gotten used to them High level abstractions like resources facilities aids requirements and applica tions still mean different things to different people This paragraph is
102. ndeed be helpful if you could tell the good reader from the bad by looking at him But this of course is impossible You cannot even tell one from the other by observing their eye movements and reading speed As educator George Klare points out in cases where experimenters used a camera they could not differ entiate the reading habits of normal people and the feebleminded Both groups read at the same speed and with the same kind of eye movements Only a compre hension test can tell which is which WRITER S GRAMMAR VERSUS READER S GRAMMAR Another point to remember is that the grammar of the poor reader is not always the same as your grammar 3 7 Thus your writing may be grammatically perfect Yet it may fail to communicate because the inefficient reader habitually distorts the grammar Donald Dansereau found this to be so in his research for the Department of Health Education and Welfare Helen Lowe said pretty much the same thing in her article in ATLANTIC MONTHLY Dansereau s readers who go all the way up to the college level were insensitive to structural cues in written material For example they got no sense of time whatsoever from the ed on a verb in a sentence like the following ty He hurried to keep all his appointments Perhaps the sentence would communicate better if the writer inserted the word yesterday The net result is clearly pictured in the words of Helen Lowa In addition to
103. ngs are applicable to both In the experiment college students listened to speeches rated low moderate high and very high in structure or organization Incidentally the very high speeches con tained transitional words and phrases and summaries of the main points After each speaker delivered his speech the students took a 30 item test Final results showed that all students without exception scored higher as the speech structure increased This chapter tells you how to gain such organization in your technical writing The chief emphasis is on two guiding principles unity and coherence In reading about these you will learn about topic sentences connectives and the concept of motion You ll also learn how to recognize the foremost example of unor ganized writing the haystack paragraph All the examples used to highlight the discussion of unity coherence and the haystack paragraph are from DEC software manuals UNITY _ The first sentence of every paragraph is a kind of contract between you and the reader That sentence in 4 1 effect tells him The paragraph will discuss the topic or idea presented in this sentence When he reads the first sentence he decides what the topic of your paragraph is Thereafter he expects you to live up to the contract to stick to your topic You break the contract and risk losing his attention when your first sentence discusses one topic and any part of the paragraph di
104. nical writer is to communicate to pass technical information along to the reader so that it becomes the common property of both The remainder of this chapter will continue the emphasis on communication as the key to the whole art of technical writing First you will see a verbal communi cation system in operation Then you will get a closeup of each element of that system A VERBAL COMMUNICATION SYSTEM Figure 1 isa simple diagram of a communication system as seen in communication theory of RECEIVER Means of transmission Figure 1 A Verbal Communication System Each system has a sender a receiver and a means of transmission The sender is the writer the receiver is the reader The means of transmission represented by the broken line in the diagram is in our case written language The wavy line stands for noise Noise is anything in the system that changes or distorts the meaning being transmitted In all transmission you the communicator try constantly to eliminate noise Since clear accurate meaning is what the communicator always strives to transmit you can get some idea of the difficulty of the task by looking at Figure 2 It shows the four forms of meaning operating in the communi cation of technical information IDEAS IDEAS IDEAS IDEAS SOURCE SENDER LANGUAGE RECEIVER Figure 2 Four Forms of Meaning The source is the meaning in specifications flow charts schematics oral and written reports and any other
105. nverter with the firing of a Schmitt trigger The real verbs in this passage are synchro nize count measure and start The revision below eliminates the passive verbs and ele vates the action words from their gram atically inferior position as infinitives Revision It can synchronize the central processor to external events count external events or measure intervals of time between events It can also start an analog to digital converter with the firing of a Schmitt trigger Original It is commonly required to retain the final data in a readily accessible medium 23 s The real verb in this sentence is retain The revision promotes it from its infinitive status and thus puts the action in the verb spot where it belongs 7 11 Revision The user should retain the final data in a readily accessible medium Abstractness Finally the experts say that passive verbs attract abstract nouns Thus in the final analysis the passive and the abstract work together to deprive the reader of the meaning he looks for in the passage In the following examples you can see how the passive allies itself with abstract nouns 1 Original The practice of documenting software is disliked by many programmers Passive verb is disliked Abstract noun Practice Revision Many programmers don t like to document software 2 Original The capability of the system to be used for solving laboratory p
106. o we leave wholly out of account any notion of the dog as a living organism ingesting food transforming it and getting rid of it Moreover we fail to focus on the dog as science sees it a mass of swirling electrons Hence dog as a word becomes a shorthand term for a small subset of the total number of specific characteristics of all the dogs in existence In sum dog is a general word The ladder of abstraction is a graphic means of showing 1 how we get more abstract and general as we ascend the ladder and 2 how we get more concrete and specific as we descend the ladder Figure 5 for instance illustrates this in the case of dog Notice that when we go up the ladder each level refers to more items and says less about any one individually LIVING THING ANIMAL BEAST CAROL S DOG DUKE Figure 5 Going Up the Ladder is More Abstract Carol s Duke for example refers to one specific member of the entire dog population Up one rung on the ladder dog designates any one or all of the approximately 100 million dogs in the world Still higher on the ladder beast can be applied to all animals except man not only dogs but also cats bears beavers elephants etc On a still higher level of generality is animal which designates any living thing that is not a plant Living thing on the topmost rung is the most abstract or general term of all it covers all plants and animals There is an important lesson here fo
107. o are set the job of writing for a technical group believe their first task is to lengthen sentences and increase the mixture of polysyllables They read technical communications in the new field noting all odd departures from standard English Thus in addition to picking up the technical vocabulary they are after they absorb the bad habits of written expression that have impeded communication for years Another view is that the new writer wants to impress the reader with his knowledge of the English language He chooses to forget that writing and speaking have the same goal to move ideas from one head to another So he abandons the level of competence he used to good effect in speaking and descends to the level of literacy A third body of opinion says that the new writer is stiff and formal because he wants to play safe Observing the style of other technical documents he fears his will seem unprofessional if written differently A final view is that his writing is complex because his thinking is complex He refuses to take the trouble to 24 simplify it for the reader In other words he refuses to work for competence in his writing RIGHT ATTITUDE Well that s the ailment What s the cure The experts offer the following suggestions 1 Always remember that your chief concern is to get your content across 2 Often ask yourself What am I doing Be honest in your answer If your answer is that you are trying to
108. occurs whenever the A379 diagnostic message is printed In this case the last card from the output side should not be replaced in the input hopper for it has already been read Average Sentence Length 21 words Three indirect command files for system generation are provided in RSX 11D Either 32KGEN CMD or 44KGEN CMD can be 6 9 used to define the system to Phase 1 instead of typing directives in response to Phase 1 requests SYSBLD CMD is always used to perform Phase 2 If the user wishes to tailor the system to a particular installation he can either edit the existing files or create new ones Average Sentence Length 14 words Flesch s formula would give a high readability rating only to Paragraph 5 Houp and Pearsall would find only Paragraphs 4 and 5 acceptable For a quick comparison of the paragraphs see the data listed below Average Sentence Houp Pearsall Paragraph Length Flesch Rating Acceptance 1 33 words Very Difficult No 2 26 words Difficult No 3 25 words Difficult No 4 21 words Fairly Difficult Yes 5 14 words Fairly Easy Yes SOME SUGGESTIONS FOR REDUCING COMPLEXITY Complex writing can hardly be called good informative writing because it makes the reader work too hard for his information So anything you can do to reduce complexity is a step in the right direction With that thought in mind here are a few suggestions to help cure this major ill of sentence complexity 1 Use this as a guidin
109. of the reader and tells whether you can cope with the required memory level Another burdensome sentence from DEC software docu mentation reads as follows By dividing the DBS files into pages and storing selected records on these pages and using a page as the basic I O buffer size DBCS operations that affect the records on only one page can be handled with a single disk access This 42 word sentence requires the reader to grasp 19 facts before he reaches the verb And to make his burden even heavier he s forced to retain 14 facts before he even gets to the simple subject DBCS operations Translated into other terms this means he must read 24 words before he gets his first inkling of what the sentence is about You can test your memory too on this one if you wish But it really isn t necessary Obviously the required memory level is impossibly high This is a first rate example of how sentence complexity can help inhibit communication Although the next example is shorter than the previous Ones it is by no means less complex In fact its complexity is so fascinating that on one occasion 12 6 4 college graduates were given this sentence as a test They had to read it then wait five seconds before stating all the facts it contained Not one of them was able to do this successfully Here it is for your edification The establishment and maintenance of relation ships between records specified by means of
110. oise as a lack of clearness Such unclearness can range from slight trouble in under standing a word or phrase to total inability to under stand any of the message A lot of noise or unclearness causes the loss of meaning shown in Figure 3 Noise can originate in the writer s failure to extract clear accurate information from his source Most of the time however noise is caused by the writer s style It arises from the six major ills of technical writing discussed in Chapters 4 through 9 of this book Poor organization of paragraphs Excessive use of abstract words The fog of sentence complexity Overuse of the passive voice Bunching together of too many technical terms 6 Vague empty and difficult words Mm hWN CHAPTER 2 WHAT THE EXPERTS SAY ABOUT THE WRITER All exposition according to the experts is written on two different levels the level of literacy and the level of competence Literacy has to do with the so called mechanics of writing with punctuation usage and grammar for example And you ll note that the mechanics lend themselves to testing and measurement Do you know what a sentence is If so you have mastered one phase of literacy Can you tell nouns from verbs and prepositions Can you use periods and question marks correctly Do you know the difference between principle and principal Do you start each sentence with a capital letter Can you detect and correct a run on sentence A
111. on the object and movement goes forward from the beginning of the sentence to the end Movement Doer of Action Verb Receiver of Action 3 The forward movement in the sentence is similar to that in thought or in actuality This is what gives the active voice its naturalness and force 4 Since the subject spot is the emphatic spot emphasis in the active sentence is on the doer of the action 1 2 The word passive comes from the Latin passivus which means suffer So in the passive sentence the subject is the sufferer or the receiver of the action If you want to include the doer of the action the person or thing that inflicts the suffering you must put it after the verb in a phrase starting with the preposition by Thus the underlined verbs in the following sentences are in the passive voice ot e John was hit by the ball The loop is initialized by the first five instructions The results of computer operations are recorded by output devices 7 The actual work of computation and calcula tion is performed by the arithmetic unit of a digital computer The contents of memory are verified by the EXAM switch Here is a summary of the important points about the passive voice l The subject of the verb in the passive voice is the receiver of the action In the preceding sentences for instance the following are receivers of the action John loop results work and contents The passive verb a
112. on of the first job finishes freeing the DECtape control for the second job The I O operation of the second job is initiated and the job is transferred from the device wait queue to the I O wait queue The first job is trans ferred from the I O wait queue to the highest priority run queue This permits the first job to preempt the running of the third job When the time slice of the first job becomes zero it is moved into the second run queue and the third job runs again until the second job completes its I O operations Comment Once again you re dealing with a paragraph whose length 276 words adds nothing to the ease of comprehension of the content And once again breaking it up is the best way to improve it Certainly it can with benefit be broken in two at the example Thereafter the example itself must undergo some drastic ameliorative surgery For as it now stands the tortuous rigmarole of the example serves more to obscure than to clarify Unexplained Series A series of phrases or clauses bunched together too compactly is another kind of density Here the writer crowds three or more advantages or functions into one sentence without showing the what or why of them The reader in likelihood will skim through them without grasping their full significance Two examples from a DEC software manual highlight this fault 1 The Real Time Clock offers the user of the Lab Peripheral System several methods for a
113. oning it in each sentence _ Another good example from the same manual A program written to perform a specific opera _ tion often includes sets of instructions which perform intermediate tasks These intermediate tasks may be finding a square root or typing a character on a keyboard Such operations are often performed many times in the running of one program and may be coded as subroutines To eliminate the need of writing the complete set of instructions each time the operation must be performed the JMS jump to subroutine instruc tion is used The JMS instruction stores a pointer address in the first location of the subroutine and transfers control to the second location of the subroutine After the subroutine is executed the pointer address identifies the next instruction to be executed Thus the programmer has at his disposal a simple means of exiting from the normal flow of his program to perform an intermediate task and a means of return to the correct location upon completion of the task This return is accomplished by using indirect addressing which is discussed later in this chapter The following example illustrates the action of the JMS in struction Here the writer promises to talk about sets of instruc tions which perform intermediate tasks And the promise is kept all the way through the paragraph A new paragraph could have been started at To eliminate the need of writing but that would be a
114. ormally terminates the executable part of a line and begins the comment part 16 words Saving From 22 words to 16 A saving of 6 words Original If the relationship is found false then control is transferred to the statement following the IF statement the next sequen tially numbered line 22 words Revision If the relationship is false then control transfers to the statement following the IF statement the next sequentially numbered line 20 words Saving From 22 to 20 words A saving of 2 words 7 Original The COS 300 2780 Remote Data Communications Package RDCP is de signed to provide remote users of IBM 360 and 370 systems with both on site proc essing and remote job entry RJE com patible with the IBM 2780 Data Trans mission Terminal Model 1 39 words Revision The COS 300 2780 Remote Data Communications Package RDCP provides remote users of IBM 360 and 370 systems with both on site processing and remote job entry RJE compatible with the IBM 2780 Data Transmission Terminal Model 1 36 words Saving From 39 words to 36 A saving of 3 words Wordiness Both Freedman and Thomas Johnson say that the passive voice and awkward wordy constructions seem to go together For example the passive verb is assumed usually calls for on the part of Too the passive is questioned drags the lengthy as to whether along with it Finally as we have seen in the examples in the
115. ormative sentences requires much skill on the part of the technical writer In fact it demands much more from you than most people realize Not only must you give the reader the facts he needs but you must also put it into chunks small enough for him to digest Yours then is a job of constant adjustment adjusting your technical material to sen tence lengths the reader can understand And you must do this more or less instinctively on the basis of what you know about the reader and the complexity of the subject matter How long should sentences be The experts say that no one can put a ceiling on sentence length They also say 6 6 _ that sentences don t have to be of a uniform length They advise you to adopt the standard of average sentence length That is some sentences will be very long some short but on the average they should be short Rudolf Flesch in THE ART OF PLAIN TALK and Kenneth Houp and Thomas Pearsall in REPORTING TECHNICAL INFORMATION are quite specific in relating number of sentence words to ease of under standing Here is Flesch s correlation of number and difficulty Number of Words Reading Ease 8 words or less Very Easy 11 Easy 14 Fairly Easy 17 Standard 21 Fairly Difficult 25 Difficult 29 words or more Very Difficult To summarize Flesch s findings he says that an average length of 17 words makes for good readability Houp and Pearsall on the other hand suggest a ehword average as
116. passive in literature and in technical writing and 5 suggestions on how to shift from the passive to the active And as was the case in the preceding chapters examples to illustrate the principles in the text are taken from DEC software documentation RECOGNIZING THE PASSIVE In grammar the term voice refers to the way the subject is related to the action expressed by the verb If the subject is the doer of the action then the verb is in the active voice On the other hand if the subject is the receiver of the action the verb is in the passive voice A sentence with its verb in the active voice usually has an object as well as a subject The object is always the receiver of the action expressed by the verb The verbs in the following sentences are in the active voice Notice that the subject is enclosed in a rectangle the active verb is underlined once and the object twice 1 John hit the ball 2 The first five initialize the loop 3 Output record the results of com puter operations 4 The arithmetic of a digital computer performs the actual work of computation and calculation 3 verify the contents of memory with the EXAM switch Here is a summary of the outstanding features of the active voice 1 The subject John instructions devices unit you performs the action expressed by the verb 2 The line of action in the sentence is direct That is the subject does the verb s action
117. pressions as industrial and laboratory data acquisition flexible high performance multi channel analog to digital A D converter and multi plex a maximum of 1024 differential input analog signals 2 11 CONCLUSION That s the substance of what the experts have to say about the writer Although they may appear to condemn technical writing that is actually not the case They realize it has been performing an essential function for a long time What they are saying is that it has obvious faults They stress the need for improvement Unani mously they urge you to sharpen your skill on the competence level they suggest that you make technical writing more readable 2 12 CHAPTER 3 WHAT THE EXPERTS SAY ABOUT THE READER Who is my reader This question will plague you every time you begin a writing task And rightly so As we have already indicated the reader is by far the most important element in a verbal communication system Indeed he is the reason it exists He influences the language of the technical document its format illustrations typography everything about it To ignore his needs then is to endanger your very prospects as a technical writer On the other hand if you create an accurate image of him and choose your words well according to that image you greatly increase your chances for success In this chapter you will observe the reader as if he is under a microscope You will see the two profi
118. r ED 090525 1974 Mosberg L and Shima F Comprehension of Con nected Discourse Educational Resources Infor mation Center U S Office of Education Docu ment Number ED 036398 1969 Palmer W S What Yolly Willy and Harriet Learned To Do The Free Modifiers A Fresh Mode of Teaching Composition Educational Resources R 3 Information Center U S Office of Education Document Number ED 059223 1971 Powers J E The Effect of Children s Expectations and Word Associations Upon the Comprehension of Passive Sentences Educational Resources Infor mation Center U S Office of Education Docu ment Number ED 078931 1973 Robertson J E Pupil Understanding of Connectives in Reading Reading Research Quarterly Volume 3 pages 387 417 1968 Rothkopf E Z and Kaplan R Exploration of the Effect of Density and Specificity of Instructional Objectives on Learning from Text Journal of Educational Psychology Volume 63 pages 295 302 1972 Scott R I Using Korzybski s Semantics to Teach English Composition Educational Resources In formation Center U S Office of Education Docu ment Number ED 040176 1969 Slobin D Grammatical Transformation and Sentence Comprehension in Childhood and Adulthood Journal of Verbal Learning and Verbal Behavior Volume 5 pages 219 227 1966 Swift M H Clear Writing Means Clear Thinking Harvard Business Review Volume 51
119. r leads him to include a discussion of statements com mands and spaces and tabs in the same paragraph without attempting to show how they are related The two uses of thus are especially weak In the first instance thus and the words with it do not expressly tell the reader that if he puts line numbers on his statements BASIC will put them in order for him On the contrary he has to read through the sentence and then go back to piece together this information The second use is much less effective How tabs and spaces modify a program is not at all clear And how they make a program more readable is vaguer still The writer could greatly increase the effectiveness of both sentences by revising them to substitute because for thus THE IDEAL SYSTEM In the ideal communication system the writer provides paragraphs that are unified and coherent the reader easily follows the writer s presentation understanding all the ideas and their relationships Granted you ll never see such a system in operation But if you follow the suggestions in this chapter for organizing your para graphs to help the reader you ll take a giant step toward realizing your part in it You ll become a more effective communicator 4 13 CHAPTER 5 CURING THE SECOND MAJOR ILL AN ABSTRACT STYLE All words are abstract There are absolutely no excep tions to this truth This is the teaching of Alfred Korzybski author of SCIENCE AND SANITY whi
120. r of the book MEASUREMENTS OF READABILITY Not only will highly readable writing get the reader to accept your manual over another but it will also attract more readers He says that readers like readable writing because they can read it faster and get more out of it OTHER FAULTS NOTED BY THE EXPERTS Most of the foregoing statements are pretty general But here are some specific faults the experts see as harmful to technical communication Again they all concern 2 6 competence in writing or rather the lack of it For each fault we have included at least one example from a DEC manual 1 The writing is dull and dry because words do not say what they mean and syntax gives false cues that force the reader to go back and read again Reading in that case says Jacques Barzun and Henry Graff is like wading through a swamp Example All files are subject to being compressed with the exception of installed task files the checkpoint file and the save image file Because of system linkages these tasks which are already contiguous are left in their original position Comment To what does the phrase these tasks refer To the task files Or to all three files The reader has to reread because reference is unclear Example All privacy locks and keys are assigned by the Data Base Administrator and the strictest security must surround their use They should not for instance appear in the DBD or
121. r is an emphatic yes This was the finding of Bonnie Meyer and George McConkie who presented a paper on this topic in April 1974 at the annual meeting of the American Education Research Association The experiments of Meyer and McConkie showed that information at the beginning of a paragraph is retained longer than that at the end In fact the deeper in the paragraph the information appears the less likely it is to be re membered An additional finding is that topic sentences at the beginning of paragraphs are remembered longer than the supporting details following them Apparently the details lose their independent identity in the reader s 3 10 memory over a period of time and merge with the information in the topic sentence This information is important when you write tutorial or instructional material Remember you defeat your own purpose when you put the most important data in the middle or at the end of a paragraph Position of Adverbial Clauses in a Sentence An adverbial clause at the beginning of a sentence is more difficult to understand and remember than one at the end Many researchers notably H Clark K Smith L McMahon and V M Holmes have proved for example that the first of these two sentences poses the greater comprehension difficulty to the reader 1 When Tom arrived everybody cheered 2 Everybody cheered when Tom arrived The reason for this really doesn t matter Suffice it to say it concern
122. r is the cluster of relationships beneath the surface Ernst von Glasersfeld a typical proponent of this view analyzes this kind of complexity into the following parts 1 The occurrence of unfamiliar relationships 2 The prospective ambiguity of certain phrases An illustration of unfamiliar relationships is seen in the following sentences about the Americans and the Japanese 1 Americans fought with the Japanese in Peking in 1900 2 Americans fought with the Japanese in Manila in 1945 In the first sentence the Americans and Japanese are related as allies whereas in the second they are related as enemies And the difference is due to the relationship set up by the preposition with In sentence 1 it means on the side of an unfamiliar usage and in sentence 2 it means against Structurally these sentences are identi cal each has an independent clause and three prepositional phrases Von Glasersfeld s concept of prospective ambiguity was discussed in Chapter 3 There we saw that the sentence The coding she did but the documentation she refused to do required more reader effort to understand For this reason von Glasersfeld called it complex Traditional grammar on the other hand labels it compound a designation that says nothing about its complexity This then is the mark of complexity as discussed in this chapter It makes the reader work hard to get meaning from a sentence And when he
123. r writing readable write shorter sentences and smaller words 6 Use structural paragraphs throughout your document Structural paragraphs serve to introduce summarize or review a topic fora reader Usually appearing at the beginning or end of a section they help orient the reader They give perspective PRINCIPLE OF LEAST EFFORT Stated simply the principle of least effort says that an individual will invariably choose to get to his goal by the route involving the least work Applying this to reading George Klare says the reader prefers readable material over the difficult because it requires less effort on his part Klare observed that people will read two grades below their level when reading for pleasure Sometimes they will tackle material above their grade level but their motivation must be powerful Usually this happens when the subject matter is very interesting or very necessary as in the case of health information or when the reader has a strong urge to learn There s a moral here Don t get the notion that you can challenge the reader with difficult passages If he sees there s too much effort involved he ll drop your book and get the information elsewhere Perhaps he ll tele phone the software specialist to get it orally At any rate you can be sure he ll take the easy road UNDERSTANDING AND MISUNDERSTANDING That s the picture of the reader that emerges from the latest research We hope we ve ma
124. r you as a writer the higher your words on the abstraction ladder the more meanings your reader can read into them Remember what we said in the preceding section Language and Reality the writer depends on the reader to relate the word to its referent Thus you can use living things to refer to dogs if you wish But you risk having some of your readers apply it to plants others to bears and coyotes still others to men or fish On the other hand the lower you go on the abstraction ladder the more specific you get Thus going down betters your chance of communicating Look at the example in Figure 6 This time let s take a different perspective Let s say that as we move down the ladder we become less abstract Figure 6 Going Down the Ladder is More Concrete Suppose the public relations group at New Look Com pany issued a press release containing the following sentence New Look expects its newly acquired asset to bring accuracy to its inventory and speed to its payroll operation The reader doesn t get much information from that sentence The word asset can mean anything at all of value So if we have no more concrete reference we could think it referred to a building a machine or a system or organization Going down the ladder here s what information the other terms convey chattel Here we have taken a small step in the direction of communi cating This term rules out real estate bu
125. re facility maintenance establishment honesty evil beauty and configuration Notice that a number of these words refer to qualities ideas conditions or relationships Concrete words on the other hand do have physical referents And as we have seen in the discussion of the ladder of abstraction concrete words are either specific or general They are specific when they refer to particular things in the physical world Carol s Duke Senator Kennedy the Declaration of Independence Digital Equipment Corporation They are general when they refer to a class of persons or things dog hill programmer physicist computer newspaper In regard to communication the consensus of the experts is that concrete words are by far the more effective As Robert Gunning says Words that stand for things we know by the senses are safest in communi cation because there is greater possibility that you and the reader will have a large area of overlap in experience with these words And Lois Van Rooy in her advice to writers of books echoes Gunning Write in terms as concrete and specific as possible In summary use concrete words for better communica tion As an aid in finding concrete words use the following three tests 1 Can this be seen or touched Does this exist in the physical world 3 Is this picturable A picturable term names something that the reader can visualize as having size and form The word car is pict
126. re you a good speller Such questions test your knowledge on the literacy level But answering them all in the affirmative does not make you a good writer Regardless of the emphasis that schools nowadays put on literacy it is not the really important level of writing In fact at least one authority implies that literacy is not a part of good writing at all The important level of writing involves the ability to move ideas from your head to the reader s This level is what Edwin R Clapp of Western Washington State College calls the level of competence Competence in writing then has to do with how well you can pass technical facts along to the reader Unlike literacy it doesn t lend itself to objective tests or measurements Can you recognize a topic and then explore it to discover its limits If so you have some skill on the competence level Can you tell which ideas belong to that subject And which do not belong Can you write those ideas in the same order as they appear in your 2 1 thinking In other words can you show one idea as the effect of the other Is one the whole and the other a part Can you show this relationship in writing Does one follow the other How do you express that sequence Can you similarly express likenesses and differences among your ideas How about equality and subordination Are you proficient in writing definitions and classifications of your ideas Can you develop theories or laws or prin
127. roblems is stressed in this manual Passive verb is stressed Abstract noun capability Revision This manual stresses the use of the system for solving laboratory problems 3 Original The chief measure of the soft ware s success is indicated by the absence of SPR s in the last three months Passive verb is indicated Abstract noun measure Revision The absence of SPR s in the last three months proves that the software is successful THE CASE FOR THE PASSIVE Despite what some experts seem to imply the active voice is not always more effective There are many occasions when the passive is much the better choice Of course the decision in regard to use rests with the writer And it depends on what you want to emphasize 7 12 If you want to stress the receiver and take the emphasis off the actor then you should turn to the passive Too if the doer of the action is unknown or unimportant you should use the passive The following sentences for example are more effective in the passive l The data center was wrecked by vandals last week Comment Emphasis is on the receiver of the action Abraham Lincoln was defeated for the U S Senate by Stephen A Douglas Comment Emphasis is on the receiver However in a paragraph about Douglas we would use the active voice and make Stephen A Douglas the subject The twelve bits of the accumulator are numbered 0 to 11 Comment
128. roduct of Lewis Carroll s lively imagination He actually exists In fact he abounds in the real world of words He writes syndicated newspaper columns and learned articles for journals and magazines His papers and reports appear in business and in science in law and in medicine indeed in every trade and in every profession Sometimes he even stoops to teach English at a high school or college But wherever he is he always shows himself as the arch enemy of communication This chapter deals with three classes of words the Humpty Dumpty writer uses to hinder communication 1 jargon 2 big words and 3 deadwood JARGON The meaning of the term jargon has changed over the years So nowadays jargon can be good or bad 9 1 In its good sense it refers to the specialized technical language of a trade or profession It is in effect a club language Thus medicine has a jargon law has a jargon baseball has a jargon And the computer industry has its jargon Some familiar examples of good computer jargon are debug program loop core memory subroutine bit block branch flag checksum software flowchart and tag Being clear and concise in meaning such words are excellent tools of communication Writer and reader alike as long as they belong to the same club know what the words mean However when such words are used in communication with nonmembers with readers who are not privy to their specialized meaning
129. rogan J A Clear Technical Writing McGraw Hill Book Company Inc New York 1973 Casey H and Clark M T Logic A Practical Approach Henry Regnery Company Chicago 1963 Crouch W G and Zetler R L A Guide to Technical Writing The Ronald Press Company New York 1964 Flesch R The Art of Plain Talk Harper and Brorhers Publishers New York 1946 Flesch R The Art of Readable Writing Harper and Brothers Publishers New York 1949 Flesch R A New Way to Better English Harper and Brothers Publishers New York 1958 Gilman W The Language of Science A Guide to Effective Writing Harcourt Brace and World Inc New York 1961 Gunning R The Technique of Clear Writing McGraw Hill Book Company Inc New York 1952 Hayakawa S I Language in Thought and Action Harcourt Brace and World Inc New York 1964 Hayakawa S I ed The Use and Misuse of Language Fawcett Publications Inc Greenwich Conn 1962 Hicks T Successful Technical Writing McGraw Hill Book Company Inc New York 1959 Houp K W and Pearsall T E Reporting Technical Information Benziger Bruce and Glencoe Inc Beverly Hills California 1973 Institute in Technical and Industrial Communications Fourth Annual Proceedings Problems of Style and Semantics in Technical Writing pages 16 20 University of Colorado Fort Collins Colorado 1961 Institute in Technical and Industrial Communications Eighth Annual
130. ruction is clearly an incon venience f the programmer later adds or deletes instructions thus altering the location assignments of his program he has to rewrite those instructions whose operands refer to the altered assignments If the programmer wishes to move the program to a different section of memory he must rewrite the program Since such changes must be made often especially in large programs a better means of assigning locations is needed The assembler assigns this better means Here in the skillful use of because however if thus and since the writer guides us through the ideas in his paragraph The paragraph is coherent because it is the verbal reflection of the writer s ordered thinking Tablel Some Transitional Words and Expressions Simple Conjunctions and Adverbs also however and incidentally sil besides likewise then but meanwhile therefore for moreover thus furthermore nevertheless too generally next usually hence similarly whatever Adverbs of Time eventually next secondly finally now when first once ultimately Simple Expressions another way to in essence instead of as well in fact more specifically at the same in general no matter what time in other words on the other for the same in short hand reason in the same to begin with in addition to sense that s what in brief in sum why in contrast in summary what s more Subordinate Conjunctions although whenever as
131. rupts his natural reading pace For another density interrupts the natural flow of ideas from sentence to sentence and paragraph to paragraph Thus he fails to get a sense of movement or continuity to carry him through the writing In a word he will probably resent dense writing because he had to plow through it Finally a dense presentation is hard for him to interpret Hence he is likely to go elsewhere for his information Bearing in mind George Klare s principle of least effort you know he won t work hard when he learns of an easier way to get the information This is especially so if he figures that you should have done the interpreting for him So in the interest of effective communication examine your writing for the kinds of density discussed in this chapter Read any questionable passages aloud to deter mine whether they sound natural If they turn out to be technical tongue twisters think about density And then set about revising them Too revise any passage in which you find it hard to insert connectives and transitional phrases Such a test should again get you to think density Once density is diagnosed what s the cure For a start use the suggestions sprinkled throughout this chapter 1 Break up dense sentences and paragraphs One spinoff benefit of such action is that you have to insert words showing relation ships Thus you will automatically be inter preting for the reader 2 Eliminate all unnecess
132. s the reader s memory span and the way the human mind processes information The important thing is its significance to you as a communicator You reduce your chances of communi cating when you place adverbial clauses at the beginning of sentences Bearing in mind the information in the preceding section you triply reduce your chances of communi cating if 1 You put adverbial clauses at the beginning of sentences 2 You make those adverbial clauses long 3 You fill them with long words As Lois van Rooy points out readability decreases as clause length increases One Clause Instead of Two Experiments by E B Coleman in 1965 showed that the reader can understand information in two clauses better than he can in one Thus the subjects in his experiments understood sentence 1 much better than sentence 2 1 If you knew the Mississippi it would be helpful 2 A knowledge of the Mississippi would be helpful And to hark back to the statements in the preceding section you can improve comprehension still more by revising sentence 1 as follows 1 It would be helpful if you knew the Mississippi Once again we want to emphasize that you compound the difficulty of sentence 2 when you add words Thus the writer of this sentence inflicts much pain on the reader 2 A comprehensive knowledge of the salient facts about the Mississippi from its discovery to the extensive government dam building projects of the 20th cen
133. scovery Five weeks later he got another message In no case can we be presumed responsible for the generation of pernicious residues from hydro chloric acid and we strongly recommend there fore than an alternative method be utilized The plumber was delighted He sent his third letter in the next mail In it he said that about 15 plumbers in his city were now using hydrochloric acid for pipes All of them liked it Now he wondered whether the good people in Washington could help him spread the news of his discovery to plumbers throughout the country At this point the correspondence fell into the hands of a rare Washington bureaucrat one who knew how to write to plumbers Within a week the plumber v was reading these words Stop sine hydrochloric acid And tell your friends to stop too It eats the hell out of pipes Certainly the letters in this interchange are a far cry from technical writing Nevertheless they offer a lesson 1 1 to the new technical writer Write so your reader can understand EK KEE The chief function of a technical writer is to inform to supply the reader with technical facts Thus each sentence you write must be aimed at the reader If your sentences are not so aimed you fail as a technical writer Your message is like an arrow shot blindly into the air It will fall somewhere But the chances are that it will not hit the target In other words you as a technical writer
134. scusses another Thus you focus his attention with the first sentence Then you hold his attention by making your paragraph stick to the topic in that sentence We call the first sentence the topic sentence In writing other than exposition the topic sentence can appear anywhere in the paragraph Consistency in sticking to the topic throughout the paragraph is called unity Briefly a paragraph is unified when all its sentences discuss the topic appearing in your opening sentence When you give such unity to a paragraph you take the first step in organizing it Here are some examples of good unified paragraphs from DEC software documentation The programmer must write a program which is a list of instructions for the computer to follow to arrive at a solution for a given problem This list of instructions is based on a computational method sometimes called an algorithm to solve the prob lem The list of instructions is placed in the computer memory to activate the applicable cir cuitry so that the computer can process the problem This chapter describes the procedure to be followed when writing a program to be used on the PDP 8 family of computers The first sentence tells us the paragraph will discuss a program or list of instructions This is the essence of the writer reader contract in this paragraph And the writer fulfills the contract not only by discussing the topic in each sentence but also by specifically menti
135. section on Wastefulness the passive is used and the infinitive invariably in its wake add up to four words that can easily be reduced to one Notice that the extra words the passive draws into the sentence are idle as far as meaning goes and serve only to obscure the words that do the work The net result of the passive and its wordy accompaniment is an unemphatic verbose style Some examples of that kind of style appear below 1 Original Debugging of the program can be achieved through the use of DDT Revision The user can debug his program with DDT 7 2 Original The user is advised that the following hardware is required in order to run this software Revision The user needs the following hardware to run this software Original A working knowledge of COBOL is assumed on the part of the programmer who wants to understand this manual Revision The programmer must know COBOL to understand this manual Deemphasis The passive helps to bury the action of the real verb in the sentence Not all passives do this but the pallid passives listed under Weakness certainly have this as a built in fault Again we turn to our documentation for sentences to highlight this fault l Original It can be used to synchronize the central processor to external events count external events or measure intervals of time between events It can be used to start an analog to digital co
136. ss What does he do in his spare time Granted you can t answer all these questions But by asking them you can get a better notion of your reader s brain power Don t forget that your words have to percolate through his mind in order to be understood Interests All the experts agree that you communicate more effectively when you use terms and examples familiar to the reader If he s interested in inventories and payrolls and you give him examples from the world of finance and banking you ll very likely lose him Ask yourself When he learns the subject how is he going to apply it This is one indication of his interests Attention to the material Where and under what circumstances will he be reading your document If he is to read it in the computer room seeking information to use in a panic situation then lists examples outlines boldface typography and quick reference tables will dominate in your presentation However you can resort to a different strategy if he can give it undivided attention in a relatively calm atmosphere In this case you can furnish longer explanations and repeat information to aid his compre hension Exactly what is the reader s situa tion Visualize it Wrile it down Take it into account Another expert Herbert Michaelson adds two more categories to the reader profile 7 Superior or subordinate to you in knowl edge You treat your subject matter differ ently for differen
137. t covers all other tan gible possessions machine This covers any complex device for doing work computer Now we have zeroed in on a particular type of machine But it could be the product of any of a score or so manufacturers DECsystem 10 More specific still We know it s computer a DEC computer But we don t 5 4 know what it consists of that is we don t know its memory size the number and kind of periph erals the specific pieces of soft ware etc New Look We have arrived at the bottom of DECsystem 10 the verbal ladder Here is some Computer thing we can actually see and touch Peripherals configura tion size software all make this designation less abstract more concrete more specific In summary the higher you climb the ladder of abstraction the more general you get The lower you go the more specific you get Stay low on the ladder for more efficient communication For when you re low there s less chance of the reader s projecting erroneous meanings into your words Abstract Words vs Concrete Words In everyday language we use the terms concrete and abstract to refer to the different kinds of words we speak or write Generally speaking an abstract word refers to something that does not exist in the physical world that is it does not have a specific referent against which it can be checked Thus component and system and implementation are abstract words in this sense So a
138. t readers The result of this attitude toward the subject matter is called the tone of your writing Does the reader know less than you about the general field your topic is in If he does simplify it However if he s an expert superior to you in knowledge give him the full technical treatment 8 Administrator or technical person Again tone is a factor The administrator is inter ested in concepts significance responsi bilities and potential He is in a word your subordinate in technical knowledge For him you must select and combine data to teach him what he needs to know to understand the software The technical person however gets the full load of technical details all he needs to know in order to use the software And Tyler Hicks prolific engineer turned writer adds a directive to complete your reader image 9 Select a particular reader From all the flesh and blood people you know choose one person who represents the readership you re aiming at Keep that persons name constantly in mind as you write Paste it on the wall near your desk Use him as the test of everything you write Ask Can he under stand this If not rewrite it so he can And it wouldn t be a bad idea to let your typical reader review the entire manuscript when it s finished There you have all you need to create a good reader image To be sure you won t use all these categories for the template of your particular read
139. technical writing where the doer is often unimpor tant Thus you should accept the statement by Menzel and his colleagues as merely a guide to improvement Don t try to eliminate the passive strive rather to curb its overuse Improvement in communication comes when all needless passives are changed to the active Here are some specific suggestions for shifting from the passive to the active 1 When revising ask of each sentence Where s the action If the verb in the sentence is one of pallid passives listed in the section on Weakness you know the action isn t in the verb Look for an active verb to substi tute for the pallid passive 2 In trying to find an active substitute for the passive look for an infinitive right after the passive verb Change the infinitive to an active verb This is what we did to the following sen tence in the section on Wastefulness 7 15 Original A READ statement is used to assign to the listed variables those values which are obtained from a DATA statement Infinitive is underlined Revision A READ statement assigns to the listed variables the values obtained from a DATA statement Active verb is under lined Or you may locate the active verb in a noun made from a verb Original When this option is assembled in the module GFRCAL and DISSKP are used in combination to determine what is to be done to the display file Noun made from verb is und
140. ten in DEC software documentation EXPAND is an RT 11 system program which processes the macro references in a macro assem bly language source file EXPAND accepts a subset of the complete macro language and using the system library file SYSMAC 8K produces an output file in which all legal macro references are expanded into macro free source code EXPAND is normally used with ASEMBL the RT 11 as sembler designed for minimum memory configurations Here you have a catalog or list of facts with no attempt on the part of the writer to connect one idea to another You can shuffle and rearrange these three sentences and they would be just as informative as they are now What is the common relevance of these facts about EXPAND If the writer had to supply a heading for this paragraph would it be Important Facts About EXPAND Or Introductory Information About EXPAND Or 4 10 As the paragraph now stands the reader has to do all the interpreting all the guessing He has no way of knowing whether the list is partial or complete Too he doesn t know whether one fact is more important than the others In a haystack paragraph all facts are grammatically equal Thus there is no emphasis no selective impact on the reader From a different software manual comes the following example Lab Applications 11 modules are available to perform operator console interaction data acqui sition data editing Fast Fouri
141. the paragraph then wait five minutes before trying to recall the facts in it Another instance of breach of contract appears in the following paragraph The Data Base Administrator must be aware of his organization s long range plans as well as of long range needs of the users For instance several groups of users might be formulating plans for data bases using interrelated data The Data Base Administrator should be able to provide common access for these users Understanding short range user plans and needs as they pertain to specific application requirements is also necessary A user 4 5 for instance might require data from an existing data base which could possibly cause conflicts with the current users interests These differences must be reconciled The Data Base Administrator has the responsibility to see that the data base is an effective efficient tool for all users Looking at the first sentence you discover the topic to be the long range plans of the administrator s organiza tion and the long range needs of the user But Sentence 4 introduces a new topic short range user plans or needs What the writer needs to do to improve this paragraph is to move his last sentence up front Certainly it wears the trappings of a topic sentence Then he should change the second sentence to read To do this he must be aware of both the long range plans of his organization and the long range needs of the users T
142. ti task loads 21 words Comment Although this sentence is shorter it has more heavy multi meaning words than the previous two Approach increased computing capacity processing power and multi task loads protect the writer s meaning from the prying eyes of the reader And the preposition under though small does nothing at all for communication in this sentence So the advice in regard to vocabulary is to stick to short words whenever they fit Every time you use a big word you sacrifice some of the meaning in your sentence As E B Coleman and C R Miller learned from their research short words are more efficient in conveying information DEADWOOD Finally there is a class of foggy words known as deadwood Because such words add nothing to the 9 6 meaning of a passage they are empty and lifeless All they do is occupy space making long sentences still longer and serving mostly to detract from the meaning of other words A passage loaded with deadwood leaves the reader with the impression that he like Shakes peare s Hamlet is reading words words words From a narrow point of view deadwood is the needless repetition of ideas Usually such repetition occurs because the writer is not paying close attention to what he is saying He says green in color for example or four in number But he knows full well that green has to be a color and four can be nothing but a number Other familiar exa
143. tury would be helpful Changes in the Logical Order of Your Exposition Experiments with college students by E K Darnell in 1963 proved that changes in the logical order of a piece of writing interferes with comprehension This means that you as a writer can expect a diminishing of reader comprehension if you alter the logical order you have led him to expect For example suppose someone had written a piece about the American Revolution for the Bicentennial In writing about the events leading up to the outbreak of hostilities he treated them in the following order 1 Stamp Act 1765 2 Declaratory Act 1766 3 Boston Massacre 1770 4 Boston Tea Party 1773 5 Destruction of the Gaspee 1772 6 Intolerable Acts 1774 As soon as he mentions 1 2 3 and 4 with their dates he has led the reader to believe he is going to follow sequential or chronological order The reader believes in other words that the writer has made a contract with 3 12 him to follow that order The writers move to 1773 then 1772 and then to 1774 disturbs his comprehen sion Later the reader will experience difficulty in recalling facts 4 5 and 6 Subject Complements Instead of Object Complements Look at these two sentences 1 Your suggestion that the programmer should do the user manual seemed to alarm him 2 He seemed alarmed by your suggestion that the programmer should do the user manual In Sentence 1 the underlined clause
144. ucation Document Number ED 066726 1972 Dittmer A E A Comparison of the Grammatical Structures of Professional Senior High and Junior High Expository Writing Dissertation for Doctor of Philosophy Degree Wayne State University 1971 Fagan W T The Relationship between Reading Dif ficulty and the Number and Type of Sentence Transformations Educational Resources Infor mation Center U S Office of Education Docu ment Number ED 071051 1971 Freedman M Seven Sins of Technical Writing College Composition and Communication Vol ume 9 pages 10 16 1958 Granowsky A Background for a New Syntactic Complexity Formula Educational Resources Information Center U S Office of Education Document Number ED 083566 1973 Harris A J Some New Developments in Readability Educational Resources Information Center U S Office of Education Document Number ED 094344 1974 Hebb D O and Bindra D Scientific Writing and the General Problem of Communication American Psychologist Volume 7 pages 569 573 1952 Holmes V M Order of Main and Subordinate Clauses in Sentence Perception Journal of Verbal Learning and Verbal Behavior Volume 12 pages 285 293 1973 Hutson B W and Shub J Developmental Study of Factors Involved in the Choice of Conjunctions Educational Resources Information Center U S Office of Education Document Number ED 090575 1974 Kowitz
145. up the same amount of storage space called a record on the disk BASIC must know the record size for the random access file in order to correctly move the pointer for that file from one data item to another The record size for a random access numeric file is set by BASIC because the storage space required for a number in such a file is always the same The storage space required for a string however is dependent upon the number of characters in the string Thus for a random access string file the user must specify the number of characters in the longest string in the file so that BASIC can set the record size accordingly This specifi cation takes place when the file is assigned to a channel Refer to the description of the FILES and FILE statements in Section 10 2 When creating a new random access string file if the user specifies too few characters an error message is issued when a string too long to fit into a record is written If too 8 6 many characters are specified for a record the strings will always fit but space will be wasted on the disk When he is dealing with an existing file the user does not have to specify a record size If he does specify a record size for an existing file the record size must match that with which the file was written Comment Part of the difficulty with this paragraph is its size 301 words But the big trouble is that its wealth of technical facts taxes the reader s memory Too
146. urable The word experience is not WHAT S GOOD ABOUT ABSTRACT WORDS Words high on the ladder of abstraction are useful as tools of thought Since you can pack them with any number of details of your own choosing you can use them as a kind of logical shorthand For example you can make the word sophistication stand for 5 years of programming experience with MACRO a working knowledge of FORTRAN and ALGOL and two years of supervising experience in data base management Clearly it is much more economical for you to use the word sophistication than the specific details it stands for The same can be said for any abstract word say optimiza tion or enhancement or quality As long as the term has definable meaning for you as the thinker you can use it with benefit in your thinking As an additional bonus you can very likely organize your thoughts better because you are dealing with fewer terms But abstract words are usually no good for communica tion So the trick is to use them for thinking and then translate them into more concrete terms when you write If however you must use an abstract word in your writing use it as a shorthand way of referring to details you ve already given For example suppose you have already described for your reader a DECsystem 10 computer consisting of the following 150K of memory a line printer 2 tape drives a disk 3 terminals a 5 6 monitor and PIP DDT MACRO and TECO Therefore you c
147. ures problem activity flexibility procedurality applications function procedure area interest process characteristics interrelationships prospect circumstance management provision concepts manner _ purpose concern measure quality condition medium question connection method reliability connotations nature respect definition necessity responsibility developments objectives situation document optimization sophistication effect option standpoint effort persuasion strategies enhancement policy substance environment position utilization establishment possibility SUMMARY You will frequently have to use abstract terms in your technical writing In doing so you should realize that the farther you get from the concrete the greater your chances of missing the reader Therefore your big need is always to know where you are on the ladder of abstraction so that you can intelligently question whether your terms will be understandable to the reader When the level of abstraction is too high consider using concrete examples to give meaning to your abstract words Too never stop trying to find a concrete replacement for the abstract term As Rudolf Flesch pointed out concreteness is even more important for successful communication than short sentences And the reason is that there is an excellent chance you and your reader will have an overlap in experience of the things concrete words stand for 5 13 CHAPTER 6 CURING THE THIRD MAJOR ILL SEN
148. xample Obviously it means one thing to a reader of COSMOPOLITAN and another to a reader of TRUE And those meanings would perhaps fail to square with the meaning given it by the reader of GAY WORLD MAGAZINE or the CATHOLIC DIGEST or THE AMERICAN ATHEIST MAGAZINE Similarly a writer who uses the abstract word vehicle to convey the notion of Conestoga wagon runs the risk that his reader thinks of a buckboard when he reads it or even a phaeton 5 7 Abstractions in the words of Thomas Johnson are detrimental to exposition because they are open to interpretation Thus they defeat the purpose of infor mative writing which should say the same thing to all the readers it s aimed at Jokingly Johnson suggested that when you don t know what you re trying to say throw in a few abstract words Further if you want to bury an idea like a needle in a haystack slip it into some abstract words Morris Freedman in his SEVEN SINS OF TECHNICAL _ WRITING puts abstractions under the sin labeled gen eral fuzziness in communication He too urges the use of specific concrete terms that say much the same thing to all the target readers Two big dangers in the use of abstractions were pointed out by Robert Gunning and Herbert Michaelson The former said that the writer gets so used to abstract words that after a while such words seem concrete to him Thus the writer is unaware of any need to question whether his words are
149. y help you transfer ideas from your head to the reader s THE WRITER S PURPOSE A lot of writing misses the mark experts say because the writer takes his eye off the target In other words he forgets his purpose You should have the purpose of your document clear in your mind before you begin to write Write it down in a single sentence and post it where you can look at it often For example you may write it as follows I want to explain all the duties of a data base administrator to a manager Or I intend to describe all the components of this operating system so that a manager will under stand what they are and what they do Or I will explain SNOBOL so that the reader will be able to write a practical program after he finishes reading the manual All these purposes have to do with enlarging the reader s knowledge or giving him a new skill As such they are your chief concern as a technical writer But you should also be aware of other purposes You have to consider your manual in relation to those of competitors Is a prospective customer likely to turn to a competitor because your manual does not explain DEC s software as well as the competitor s manual does his Too are you interested in gaining the largest possible readership for your document If either of these purposes applies in your case then you d better aim to make your document highly readable This is the suggestion of George Klare autho

"user manual"

Contents

Download Pdf Manuals

Related Search

Related Contents

&quot;user manual&quot;

Contents

Download Pdf Manuals

Related Search

Related Contents

"user manual"