Computing Reviews

Designing and writing online documentation: help files to hypertext
Horton W., John Wiley & Sons, Inc.,New York, NY,1990.Type:Book
Date Reviewed: 02/01/92

Documentation is hard. This truism is accepted by several groups, including those who make a living documenting products created by others, those who must attempt to document their own creations, and the masses who seek to use the documentation created by the previous two groups. This book is not about documentation in general. All to the good, Horton concentrates upon online documentation, opening the first substantive chapter with the title “What Should and Should Not Go Online.” This chapter is followed by, among others, chapters on “Designing Human-Computer Dialogs,” “Making Information Accessible,” “Writing Online Documents,” and “Help Facilities.” The author even devotes a chapter to the use of pictures, sound, and motion.

The author’s watchword seems to be caution, based on mistakes he has seen in practical experience. Design is emphasized again and again. In my view, this emphasis is as it should be, for the same reasons I have emphasized design in software development [1,2]. The end product is more consistent, easier to understand, and geometrically less costly to maintain.

Horton provides an excellent bibliography, with hundreds of up-to-date citations to both written and online articles, books, and research efforts relating to documentation. This book is a practical guide to the accomplishment of a specific task, however; it is not a textbook, and would not work as such. Fortunately, the author does not claim this territory.

Any shortcomings are minor. Horton includes a comprehensive index. Unfortunately, the type used is much smaller than that of the text body, so much so that a magnifying glass may be sought. This seemingly small detail violates some of the author’s own premises, and may have been imposed as a money-saving move by the publisher. More substantively, the subtitle Help files to hypertext is misleading. A slim chapter of 24 pages is the whole hypertext discussion, and it is simply too superficial to be of much use. HyperCard itself is discussed elsewhere, and Horton is virtuous enough to briefly point out the shortcomings of hypertext. Other works do a better job if one wants to examine hypertext in detail, however, such as Nielsen [3].

Overall, this book is well written and useful. I recommend it highly to all those who need to create, critique, or even test online documentation. Buy it--and better yet, read it and use it.


1)

Bellin, D. The structured systems development manual. Yourdon, Englewood Cliffs, NJ, 1990.


2)

Bellin, D. Software maintenance: the small systems management guide. Prentice-Hall, Englewood Cliffs, NJ, 1991.


3)

Nielsen, J. Hypertext and hypermedia. Academic Press, Boston, 1990.

Reviewer:  David Bellin Review #: CR114511

Reproduction in whole or in part without permission is prohibited.   Copyright 2024 ComputingReviews.com™
Terms of Use
| Privacy Policy