Friday, August 27, 1999

Dynamics in Document Design. WebWorks Publisher

This article appears in slightly different form in the July/August 1999 issue of IEEE Micro © 1999 IEEE.

This time I review a book and a software package. The book sets out to help you create documents that are "less ugly and less confusing." The software package helps you produce printed and online hypertext documents from a single source. Its documentation could have benefited from the precepts in the book.   

Documents for Readers

Dynamics in Document Design by Karen A. Schriver (Wiley, New York NY, 1997, 592pp, ISBN 0-471-30636-3, $44.99)

Karen Schriver holds a PhD degree in rhetoric and document design from Carnegie Mellon University. She is a former professor and a former co-director of CMU's late lamented Communications Design Center. She now runs her own research and consulting firm. The essential messages of her book are the following: 
  • The way readers interact with documents is more important and more complex than most people realize.
  • Words and images interact in surprising ways to produce their combined effects on readers.
  • Designers can obtain useful information from classical rhetoric, experimental psychology, and usability testing. 
"Know your audience" is one of the main rules of technical writing. Creators of instruction manuals and online help systems routinely perform an audience analysis before they begin. Before Schriver's book, however, document designers didn't really know what to do with the information. Schriver shows that designers hit this dead end because the next step is neither simple nor mechanical.

Engineers, scientists, physicians, and many other professionals routinely carry out tasks that are neither simple nor mechanical. Their education and training give them the tools they need. Document designers, on the other hand, usually lack comparable education and training in document design. Their main resources are collections of valuable but superficial rules, and software packages that help them enforce those rules.

Designers who get beyond the cookbook level usually do so haphazardly -- slowly accumulating principles and techniques that pertain to their own contexts, but rarely generalizing them for the benefit of the entire profession. Schriver tries to "capture the texture of the choices" experienced document designers make and "represent the subtlety of the knowledge they rely on in carrying out their work."

Schriver's book is important, because it makes a real contribution in this direction. Through examples from her research and consulting, she helps us form a realistic picture of the people who use documentation and the problems they have doing so. Document designers who read this book carefully will come away with increased sensitivity to their audience. They will also have a clearer picture of the gaps they need to fill in their own knowledge and skills. Educators will come away with good ideas for improving curricula in technical and professional communication.

The book is scholarly, well organized, and a gold mine of ideas, but it would benefit from sharper editing. One example is the way Schriver describes her research work. Her audience -- "those who would like to further improve their work with verbal and visual language" -- have to wade through details of research procedure and methodology that have little to do with improving document designs.

Sharp editing would also reduce the 150 pages Schriver devotes to "situating document design." This is extremely interesting background material, and some of it is central to the main themes, but Schriver gives us little help in separating the wheat from the chaff.

VCRs are the symbol for inscrutable technical products with frustrating documentation. Two of Schriver's best examples deal with VCRs. I especially enjoyed reading about her attempts to use a pair of VCRs to edit videotapes she had made.

Schriver and a colleague recorded their efforts to connect the two VCRs, a cable outlet, a converter box, and a TV so that they could edit tapes and at other times watch or record cable TV programs. This is a predictable use of the equipment. The manufacturers could have foreseen and provided instructions for this task. Instead, before they found ways to simplify the problem, Schriver and her colleague confronted a problem space of over 5000 plausible combinations of wiring and settings. It took them ten hours to find the right combination.

Schriver concludes that changes to the product design and the documentation could have simplified the task. The main product changes she suggests are
  • Standard arrangement and naming of inputs, outputs, and functionality.
  • A display to help users monitor the effects of different wiring and settings.
The documentation changes are
  • Anticipation of and instructions for tasks users might wish to perform.
  • Illustrations to give users a mental picture of how signals pass through the system.
  • A clear distinction between settings that are essential for connecting and operating the equipment and those that merely support "creeping featurism."
  • Clear explanations of the effects and interrelationships of the possible settings and connections.

Her ten hour ordeal also gave Schriver a chance to experience personally another of her research findings: people tend to blame themselves for not understanding faulty products and documentation, but in fact, most people read instructions, try hard to make things work, and don't give up easily.

A key part of Schriver's book deals with typography and space. Schriver weaves together theories about rhetoric, facts about type legibility, experimental findings of the gestalt psychologists, and practical techniques for arranging material in grids.  The strength of this section is the way it draws together many factors -- making it difficult to summarize. Document designers will come away with few prescriptive rules but with enhanced sensitivity to helping readers see the structure and interrelationships of the text.

The material about typography and space is complex but clear. Schriver's discussion of the interplay of words and pictures is a little fuzzier. Even though she is able to distill a page of guidelines from the material, Schriver acknowledges that this is an area of ongoing research. She analyzes an attractive but ineptly designed website to help show how important it is to pay attention to this area -- and how easy it is to make words and pictures work at cross purposes.

Schriver finishes this substantial book by offering evidence, in the form of research studies, that paying attention to reader feedback improves document quality. At the same time she acknowledges that we don't fully understand how to obtain, interpret, and use such feedback.

In summary, this is a valuable book for anyone who wishes to inform or persuade others through words and images. But don't expect answers on a silver platter. If you don't intend to work hard to put the lessons of this book into practice in your own work, you won't get much benefit from reading it.


WebWorks Publisher 2000 for Windows (Quadralay, Austin TX,, $895)

In Silicon Valley and much of the rest of the world, Adobe FrameMaker is the tool of choice for designing printed manuals. Many FrameMaker users wish to produce hypertext versions of the same material for use on websites or as online help. The principal tools for producing hypertext, however, can do little with FrameMaker output.

WebWorks Publisher is the exception. It transforms FrameMaker output into a variety of hypertext formats. It achieves great flexibility through the following features:
  • Exploiting the structure that FrameMaker's paragraph, character, and table styles impose on the content.
  • Generating hyperlinks from FrameMaker markers (such as those used for cross-references and generated tables).
  • Enabling users to design templates for different kinds of hypertext pages (for example, contents, index, body).
  • Specifying all of its mappings as programs in a powerful macro language.
In short, WebWorks Publisher extracts every bit of structure that it can from the FrameMaker output, then allows you to control the mapping of each element to achieve whatever effect you wish.

So far, so good, but all this flexibility presents you with a substantial programming problem. Quadralay provides project templates that let you map your FrameMaker output in acceptable but unimaginative ways. To achieve the kind of flexibility most designers are likely to want, however, you need to write some macros. At that point you must confront Quadralay's documentation.

The product has no printed documentation, but Quadralay's online help is thorough, informative, and authoritative. It appears to have been lovingly written by the product's designers. The only problem is that it is not very helpful. For example, many users will start at the first topic under Using WebWorks Publisher, namely, Managing WebWorks 2000 Projects. This largely vacuous topic leads to the detailed Setting Project Options topic. This topic states clearly what each setting means, but it gives no information about why you might choose one setting over another. It doesn't help you think about how to set up a project that fits your work style.

I found myself slowly increasing my understanding as I dived into topic after topic. The information seems to be there. The authors provide lots of facts but little indication of their significance.

WebWorks Publisher is a powerful tool -- perhaps the only sensible choice for a FrameMaker user -- but learning how to use it is a research project. If you decide to use it, allocate plenty of time for learning, or hire a consultant to bring you up to speed.