I had a mountain of documentation. The compiler provided seven manuals, plus I had three additional volumes: a total of 3,974 pages. The User's Guide (that gave me directions for installation) went on to give information about creating complex Windows programs -- and I did get a rather clumsy Windows program to run -- but it told me nothing about execution of my rudimentary DOS program. I consulted a manual titled DOS Reference. It opens with a discussion of memory management and processor registers: not even close to what I needed to know.
As I was about to quit in frustration, I remembered seeing something printed on the back of the rather large carton in which the manuals and disks were shipped. Sure enough! There was a paragraph of explanation of how to run a DOS program. I wondered aloud (with expletives) why in the world a manufacturer would put such information on the box, but not include it in a manual where a programmer using the compiler for the first time could easily find it.
I was reminded of a comment in the most widely-used book on C programming; to learn C, students should start by executing a simple program to print the words "Hello, world" -- exactly what I was attempting to do:
This is the big hurdle; to leap over it you have to be able to create the program text somewhere, compile it successfully, load it, run it, and find out where your output went. With these mechanical details mastered, everything else is comparatively easy (Kernighan and Ritchie, 5-6).The point is not that it is so terribly difficult to understand how to create and run a program, but that since no useful work can be done until such mechanical details are mastered, they ought to be clearly documented -- and they almost always are not.
The printed documentation and reference manuals for all kinds of technical products that are supposed to be guides for the user are often badly written and poorly organized; computer documentation is some of the worst. Some sentences are so muddy that their meaning can only be guessed. Time and again an essential principle is assumed, but never explained -- or it is explained hundreds of pages after it is first needed.
A bright, highly-motivated programmer I knew wanted to run his programs on an operating system he had never used. Since no one was at hand to help him, he read guides, handbooks, and all the printed and on-line documentation he could find. When he attempted to use the system, none of his programs would run -- not one. He tinkered with his program code. He reread the texts. Finally, he gave up in despair. He considered it his failure, but in reality it was a failure of the documentation. There is something seriously wrong when a patient computer professional with sufficient background, intelligence, and time cannot learn to use an operating system from the documentation.
It is obvious that computer user manuals are difficult to use. In most offices that use computers, it is common to see software packages collecting dust on a shelf because no one could learn to use them by reading the manuals. Some research has shown that those wanting to learn to use a particular computer package will turn to the guides and manuals only as a last resort. They would rather stumble around with trial and error, ask others for help, or do anything rather than read confusing manuals.
Corporations that produce software might not realize that their documentation is poorly written, or, more likely, they do not know what to do about it. It is difficult to believe that they do not care. In any case, it is a sad observation that computer programs, such as operating systems, can be created that are monuments to the power of the human mind, but documentation cannot be written to describe how to use them.
No doubt computer manuals are poorly written for the same reasons any kind of documentation is poor. Those who create guides for computers may lack sufficient training in writing. They may never have read, let alone have analyzed, models of well-written text. Practice is needed; those who write well have done an enormous amount of writing. The wrong people may be writing the documentation: computer programmers are probably not the best writers of user manuals; even if they have writing abilities, they are too close to the software, and they are rarely motivated to produce clear documentation. Also, good writing requires time. In the rush to market a new computer product, perhaps insufficient time is allowed for the production of clear guides and manuals for its use.
Poor computer documentation will almost certainly be produced by a writer lacking imagination. Clear instructions can be written only by imagining what it is like not to know something -- and there is a lot to know about computers. It is extremely easy to assume that users know things that they do not know.
Suppose the installation instructions for a DOS software package contain this sentence: "Your system must allow twenty files to be open at once." If there is no further explanation, the writer of the instructions is assuming that the reader of this sentence knows that it means that the line "FILES=20" must be contained in a file named CONFIG.SYS and that this file must be on the root directory of the boot disk, and that the reader has access to and knows how to use an editor that produces a text file without formatting codes in order to create or edit the CONFIG.SYS file.
An imaginative writer would probably not assume that the user knew so much. Such a writer might, instead, suppose that the user had never heard of a file named CONFIG.SYS, and would explain how to create or edit it. (PC users who know their system has a CONFIG.SYS file, often consider it a baffling mystery -- although they may have learned that making changes in the file can have alarming consequences.)
Writers of step-by-step instructions who have limited imagination almost always fail to mention at least one essential step. For example, if a CONFIG.SYS file is edited and saved, the system must be rebooted before the changes take effect. It would be easy to forget to say that. In such a case, a user who painstakingly followed instructions only to find the software did not run, would be understandably disheartened; finding that the software worked fine the next day when the computer was started would be mystifying and confusing. Almost nothing is as frustrating as a problem that disappears (or returns) inexplicably; anyone who works around computers has heard the outraged cry: "It didn't run yesterday, but today it does, and I didn't change a thing!"
Writers (and programmers) even need to imagine the user's reaction to the screen messages produced by a program. A friend told me that he did not like to use the computer at his library because it insulted him. He said that when he entered a command the computer did not consider valid, it called him a cripple: the message was the single word INVALID.
The best assurance that technical writers have the indispensable imagination to write good computer documentation is their completion of a traditional liberal education in the arts and sciences. Enormous imaginative power can be developed by following the three-part inventions of J. S. Bach, by grasping the ideas of Descartes or Pascal, and by conceiving the fictional worlds of novels by Austen, Dickens, and Faulkner.
Training in computer science and practice in technical writing are certainly necessary, but they are not sufficient to produce good writers of computer documentation. In composing even a modest instruction manual, the writer needs to use imagination at a thousand points in order to know what needs to be explained to users. It is probably significant that many in the computer industry know "Pascal" only as the name of a programming language.
The expansion and strengthening of the imagination provided by a liberal education can provide better documentation writers. Increasingly, smart personnel officers of computing corporations will prefer to hire those with a liberal education. It is an excellent means of producing more readable documentation; that will mean more software sales, and, thus, greater corporate profit -- but, above all, it can mean less frustration for users. It might even produce documentation that would allow new compiler users to print "Hello, world" on the first try.
Work Cited
Kernighan, Brian W. and Dennis M. Ritchie. The C Programming Language. Second Edition. Englewood Cliffs, N. J. Prentice Hall, 1988.
Eric Johnson is Professor of English and Dean of the College of Liberal Arts at Dakota State University. He is the author of over one hundred articles and papers about computers, writing, and literary study. He can be contacted via email as JohnsonE@Jupiter.dsu.edu
Página creada y actualizada por grupo "mmm".
Para cualquier cambio, sugerencia,etc. contactar con: fores@uv.es
© a.r.e.a./Dr.Vicente Forés López
Universitat de València Press