Documentation: Effective AND literate

ABSTRACT

The purpose of this paper is to show how documentation can be literate, in a stylistic sense, and still be effective. Literate prose is a powerful tool that, when properly used in computer documentation, can take advantage of the full power of the English language. This does not mean that all computer documentation must or can read like a Nobel Prize novel, but neither does it have to read like a military cryptogram. A happy medium — founded on healthy grammar and syntax, and following the logic of the software being documented — is a good AND obtainable goal. The roots of the problem of literate documentation lie in a common complaint from software users: “The program looked great in the store, but the documentation is so awful that I can't get it to work!” This is particularly acute in the field of educational software — but applies across the board — because the product cannot fulfill its purpose nor its potential unless it can be effectively employed. The problem is usually caused by an excessively technical focus, and/or poor composition (that obscures the information). A person should not have to be a computer scientist or a programmer to use software; that would defeat the purpose of the product. On the other hand, the user should not need to be a philologist to discover the author's intent. In short, documentation we compose needs to be truly “user-friendly.” The major obstacle to producing effective documentation is selecting the appropriate conceptual approach. The two main tendencies when tackling the problem are both extreme: often, there is either over emphasis on academic modes of expression, or on the technical aspects. These are often inappropriate as people want beginning words and concepts when they are “beginners.” They will enjoy high-tech once they grasp the basics; they want to how-to, not why. This “how-to” label is a critical issue in developing a good conceptual approach to documentation. In the field of software documentation, the “technical writing” mindset can often derail what would otherwise have been an effective product. Far too many people are seriously misled by the term “technical” writing and it is unfortunate that the word has been so broadly applied. The use of “technical” conjures a dominant notion that, in our case here, the writer must tell the reader all there is to know about hardware and programming. If the purpose of the document is to explain such things, then that is certainly fine and can legitimately be called “technical writing.” However, the technical details are often precisely what the non-technical user does NOT need to know; most really do not care about the electronic complexities, they just want their program to work. Hence, they need “practical” documentation: that is, documentation that tells them how to perform a function or set of functions so they can do whatever it is that they want to do (one might also wish to define it as being task-oriented or task-specific rather than technology-oriented). So, the rule of thumb should be to tell them NO MORE than what is necessary to use the program. There is also an economic bonus attached to practicality. Supporting documentation that is unnecessarily abstruse will deter program use, and it is altogether likely that further offerings would consequently not sell. Keeping it “sweet and simple,” as they say, also keeps it saleable. The term “practical writing” is preferrable to “technical writing” because the term conceptually moves away from a nuts-and-bolts orientation toward a “how-to” approach. Despite the fact that computers have been with us for some time and that personal computers are now the rage, the average user still feels somewhat intimidated by the machine and its accoutrements. Therefore, they certainly do not need to be further put off by the software they wish to use. Any computer magazine or journal you can select will show the current over-emphasis on hardware, diskettes, and their capabilities. However, a corresponding under-emphasis on the accompanying documentation exists. For example, in five recent issues of BYTE magazine, there were 134 feature articles of which only TWO would be of any use to documentation writers. That is rather sad. As the educational software market grows by leaps and bounds,1 and more and more companies become involved in similar enterprises for internal training purposes, it is imperative that not only the programs themselves be impressive and intellectually stimulating, but the accompanying documentation must really SUPPORT the program. Steve Halpern, vice-president of Classroom Consortia Media, Inc. (Staten Island, NY), addressed the problem — for both programs AND documentation — thus: “The computer should be a non-threatening tool to help the teacher. So software needs to be free of problems, of any kind of sophisticated codes that have to be put in to make it work. It should have all kinds of error-trapping that lets it do what it's supposed to do, which is reinforce learning and teach concepts.”2 The computer should not be designed as a teacher replacement but, rather, to be a challenging teaching aid and learning tool. Consequently, the accompanying documentation needs to be much more than merely a textbook supplement or user's manual. Rather, it needs to be a bit of both, which is a difficult marriage to be sure, but necessary. We who produce documentation of this sort (and others) MUST be sensitive to the genuine needs of those who will be using the programs and their supporting material. This is to say that we must seriously consider our potential audience and resist the temptation to just “crank out” a document. The maxim “haste makes waste” certainly applies here. Kathy Yakal, Editorial Assistant for COMPUTE'S! PC & PCjr magazine, has said, “Courseware should be enjoyable, open-ended, and exciting. And humorous. Intriguing. Authentically pleasing. It needs to be easy to use. It must present concrete demonstrations of abstract ideas whenever possible. Provide constructive feedback for errors. Be accompanied with clear and complete manuals.”3 Equally important, it must also teach by its own example: which means that it should not include the kind of grammatical errors that are displayed in the foregoing quotation. The writer must be dedicated to producing documentation that is just as grammatically sound as it is accurate because poorly expressed information is worth little or nothing. Consequently, to produce a document that will function as an effective information base, the writer must walk a tough but necessary tightrope between two extremes. Information must be clearly expressed, and there is just no excuse for ignoring the rules of good English composition. To produce good documentation, we need to be very sensitive to writing as a mechanical process and the strategies employed by writers to present the information necessary to fulfill the required task. One might have all the best intentions of blending the academic and technical approaches, but you know the destination of the road that is pved with good intentions and those intentions go nowhere unless the writer produces really balanced copy. Even talented writers need training to produce consistently effective documentation. The preferred method is formal classroom instruction where the individual can learn various strategies and tactics and gain some intensive practice in the writing and production craft. However, as anyone in business knows, the time necessary for this process is often a luxury. Short company-sponsored workshops can be of assistance, but time is money and money is a precious commodity. With what, then, are we left? With the right tools, a lot can be done on one's own to become a more effective communicator. There are several sources in the marketplace that can be valuable as self-study materials as well as important job aids.4 They will certainly not replace a formal course, but they can at least serve as useful on-the-job training materials. Let us consider a pedagogical tool I devised while teaching tech writing at the College of Staten Island-CUNY that graphically displays the relationships between the five principles of practical writing: organization, clarity, exposition, accuracy and validity. I rather egotistically call it “Burdett's Pentagon.” The arrows are all double-headed simply because the mutual interdependencies are critical to the strength of the whole structure. ORGANIZATION: Organization is the basis of a document. Without proper logical structure, a document will fall flat on its face. Consequently, when planning a document, organize it according to the canons of logic as displayed in a normal syllogism (a word equation). Premise / Purpose / Problem Conditions / Evidence / Information Conclusion / Result / Solution This is an oversimplification, but pursuing this tack will keep a writer properly focused on the necessary steps. It is amazing how much documentation falters because the information is not presented in a logical sequence, and there is nothing more frustrating to a reader than to have to keep questioning the author's meaning. EXPOSITION: Exposition is text production and all its appurtenant features: proper grammar and syntax, effective vocabulary, appropriate reading level, and so on. This is where the writer's style will have the most direct impact and a talented writer should have little trouble. For those with average skills, the task will be more onerous. But, if they follow the syllogistic format, they will at least be able to produce satisfactory copy that will be logically consistent and do the job. CLARITY: Clarity is the connection between organization, exposition and accuracy. If the organization is not clear, the exposition will be muddied. If the data are not clear, then the points one is trying to make will be correspondingly obtuse. For our purposes, clarity is more a psychic requirement: that is, always keep the principle in the front of one's mind as a constant check on the work being performed. ACCURACY: Accuracy applies to the data or other information used in one's document. Quite simply, if the information is not accurate, the whole thing falls apart regardless how well organized or well expressed it might be. VALIDITY: Statisticians will be familiar with the concept of validity5: that is, accuracy itself is not all that is required for good documentation. In addition, we must ensure that the information used pertains to the points we are trying to make. It may well be accurate, but if it is not germane to our subject, the exposition will then be meaningless. It is fairly clear that if any one element of the pentagon is weak, the whole document will then be unsound. Devices such as this simple tool are often helpful to talented writers who may produce poor documentation because they are harried and harassed. English is a very rich tongue that, when properly employed, has tremendous potential for accurately and effectively transmitting instructions and information. Documentation writers should be particularly sensitive to the necessity of employing proper grammar and should utilize appropriate vocabulary because these documents (especially educational software) also teach by example. For instance, I cannot count the number of arguments I have had about the spelling of “through.” I consistently heard lamentations like: “But the road signs say 'thru' traffic, so…it must be OK.” Another example is the roaring battle I once had with another writer who actually said, “What difference does it make if the grammar is bad? It's a science program!” Regardless the subject, there is absolutely no excuse, especially in education programs but also in general, for sloppy exposition. Therefore, when composing documentation, let's be tough on ourselves and do it right, or don't do it at all. One's exposition is often sloppy because one has developed sloppy habits. Therefore, develop good habits, do things the proper way, use the full power of the language, and one's documentation will be exemplary. If we recall the pentagon, poor exposition can adversely affect the clarity of the document and obscure the information that one is trying to convey. Let's not take shortcuts just because it is easy. Let's not invent words (as “prioritize”) when the language already has a perfectly good word that sounds much less jarring (as “rank” or “order”).6 However, at present, there is a lot of documentation on the market that has such faulty punctuation, infantile vocabulary, excessive jargon, poor expression, that it would seem that few writers care whether they set a good example or not. Therefore, to be literate in one's composition is ALSO to be effective: instructions and information will be easy to understand, the documentation will thus mesh well with the program and will succeed in molding a comfortable computer-software-human unit. That's being truly “user-friendly,” literate and effective.

REFERENCES

• 1: See: Martin Porter, "Knowledge for Sale," PCjr Magazine, 1 (1984) 7, pp 29- 32.
• 2: Kathy Yakal, "Educational Software: What Educators Like To See," COMPUTE! 's PC & PC~r (June 1984), p. 30.
• 3: Ibid., p. 31.
• 4: Some that I particularly favor are the following: Walter E. Oliu, Charles T. Brusaw and Gerald J. Alred, Writing That Works: How to Write Effectively on the Job, 2d edn (New York: St. Martin's, 1-~4) ; Charles T. Brusaw, Gerald J. Alred and Walter E. Oliu, Handbook of Technical Writing, 2d edn (New York: St. Martin's, 1982); Robert A. Day, How to Write and Publish a Scientific Paper, 2d e~dn (PhiladelphTa: ISI Press, 1983); Cora L. Robey, Alice M. Hedrick and Ethelyn H. Morgan, New Handbook of Basic writinq Skills, 2d edn (San Diego et al.: Harcourt Brace Jovanovich, 1984).
• 5: For instance, ,=_e: Ralph H. Kolstoe, Introduction to statistics for the behavioral sciences (Homewood, IL: The Dorsey Press, 1973), pp 191-196.
• 6: For a good laugh and a check on one's own tendencies to "jargonize," I strongly recommend the monthly "Non-Word" section in the Armed Forces Journal International -- it is instructive and amusing.

INDEX TERMS

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

General Terms:
Documentation