Since the first days after ENIAC, technical documentation of hardware and software has always been poorly written and presented, an unimportant afterthought. Several authors of computing texts, including me, created their books by translating vendors’ documentation into usable English. Now Haramundanis undertakes the task of helping novice technical writers prepare vendor documents that are usable without interpretation. She takes the position that technical writing is not scientific writing but is much like investigative reporting, because it requires the rapid gathering of information, the identification of an audience, analysis, intuition, creative thought, and imagination. She defines technical documentation as “any written material about computers that is based on fact, organized on scientific and logical principles, and written for a specific purpose.” She classifies documentation into three types according to its purpose--to sell, to report, or to instruct.
After a general introductory and definitional chapter, the author describes careers in the field, gives practical precepts and development techniques, tells how to make a document attractive by using graphics and layout, and ends with a pair of less satisfactory chapters on software and hardware. The end matter includes a list of societies, conferences, and journals; a few printing and publishing standards; a historical timeline of the development of writing; a glossary; and an 18-page “select” bibliography, in which the few “excellent” works are indicated.
The precepts, tips, and advice are excellent and presented in the crisp, direct, clear, readable, logical, and attractive form and style recommended by the author. If read through from beginning to end, as recommended, the book should help the neophytes it is aimed at, although it is more likely that they will assume it is just another instruction manual that they can skip around in. Unfortunately, this book and others of its kind will never be read by those who need them most, the college professors of computer science whose miserable writing styles are imitated by their students and thus perpetuated into current computer literature of every kind, including technical documentation.
It is a fine book, the best in its class so far. I quibble that AFIPS is listed as if still alive and Computing Reviews is not mentioned at all. The hardware and software chapters are too DEC-oriented, leaving out, for example, reference to the most-used PC word processing systems. But these chapters are at the end of the book, and most readers will never get to them. Appendix C, a timeline of the development of writing from 3500 B.C. to A.D. 1988, seems superfluous, but could be used as a test by requiring students to criticize it by applying Haramundanis’s own criteria of quality, especially as to whether it is appropriate.