New Communication Issues for Technical Documentation

Charles Butcher
Consulting Engineer, N-Compass Consulting Pty. Ltd.
Email: Charles.Butcher@ncc.com.au

Abstract

Since the late 1960s, studies in Human Factors and Accelerated Learning have identified the importance of involving as many senses as possible. Traditionally, technical documentation has consisted of the written word, possibly accompanied by diagrams. Production cost or complexity has often ruled out the use of colour.

Multimedia has been adopted quickly in the educational and marketing environments. Its benefits can also be exploited in the technical arena. Not only does the effectiveness of the information improve, but new business efficiencies and cost savings are also realised.

By adopting multimedia publishing, organisations can improve dramatically the quality and effectiveness of their technical literature and, for the first time, enjoy quick and concise statistical feedback on the usage patterns of their audience.

1 The Case for Multimedia

As technology advances and as systems become ever more complex, the need for rapid, accurate understanding of these systems also increases. For a long time, technology has been outstripping the ability of developers to communicate effectively with users.

Whilst technology itself has benefited from orders of magnitude improvement in performance, integration and automation, the media via which it is described, have changed hardly at all.

Researchers into human factors have known for a long time the importance of all five senses, specifically as they relate to the process of communication. Dilts (1983) and McLuhan (1964) both identified the cultural bias toward typography, to the exclusion of the other senses or representational systems, as Dilts calls them.

It can be argued that regardless of the perceived benefits, it has in the past been impractical to provide much beyond printed manuals. Multimedia has changed this almost overnight. The education and marketing sectors quickly recognised the obvious benefits of multimedia's ability to engage other representational systems. It is time now for the technical publishing industry to follow suit.

There is now no practical impediment to the production and delivery of technical documentation in multimedia format. There is also no financial penalty for doing so.

Without the use of multimedia, the costs in money and time of disseminating information about complex technical systems will start to become the limiting factor in the acceptance and uptake of these new systems.

2 Benefits

2.1 Cost

In the author's experience on a current project involving an installation manual, it would have cost half as much to buy a digital camera and take photographs of equipment to include as diagrams as it was to have a technical writer draw facsimiles of the equipment using a drawing tool. In this area, the ability to take photographs and shoot videos in order to illustrate a point can offer savings in technical writers' time that will amortise very quickly the purchase cost of the camera equipment.

For a moderate size documentation release, the cost of a 1000-page laser printed ring-bound manual is about twice the cost of releasing the same data on CD-ROM. This does not include professional printing and binding costs, nor shipping costs. A CD-ROM writer and software costs about as much as a medium size laser printer.

With respect to training, the traditional approach has been to deliver user documentation and, in some cases, offer an optional training course. More often than not, the course would come with its own training manual and require a live presenter. Multimedia now presents the opportunity for the user documentation to be an integral computer-based training course as well.

2.2 Quality of Information

The cost comparison above is based on providing the same information in different physical formats. The CD format already may have some advantages in being able to support keyword searches and even hypertext links, but that is only the beginning.

The real advantages start to come when we begin to add the other multimedia elements to the documentation. Colour photographs and diagrams can be added without significantly increasing production costs. We can also add video clips and sound bytes containing spoken instructions or maybe examples of audible alarms generated by the equipment.

Harrison (1995) has quantified some of the improvements in comprehension and reductions in errors that multimedia style documentation can provide. She concludes that properly designed multimedia documentation will normally produce faster, more accurate comprehension and less operator error than plain printed documentation.

2.3 Quality of Feedback

Most technical writers receive precious little feedback regarding the users perceptions of their work. The effectiveness of their communication can generally be measured only via response questionnaire cards shipped with the manuals. This in effect provides some form of random sample, most likely skewed heavily in the direction of criticism. It is unlikely to reveal what works.

Commercial software is being released with usage-tracking code built in because of the extremely valuable and objective data it can provide. No amount of questionnaires or user focus groups can provide such accurate and quantitative feedback.

By adding a feedback button to the end of each page of an HTML document, the user can quickly and easily provide qualitative feedback via e-mail.

In the case of documentation accessed via a web server, accurate, quantitative detail of usage patterns can be obtained by counting the number of times pages are accessed. For a technical writer, it is just as important to know at what users aren't looking. This is the first time there has been a practical way to discover such information.

2.4 Updates

The tedious and error-prone process of updating documentation can be automated by mechanisms which periodically check a web site or bulletin board for updates; for example, an applet delivered with the original documentation CD could check the vendor's web site for updated pages.

3 Progress So Far

At the time of writing, the pilot project that will use these new techniques has just started. Management and users have been canvassed, and all are convinced that this is a good idea. Research into tools and equipment is ongoing and acquisition of the recommended hardware and software has been approved by management and most of the required equipment has arrived. We are experimenting actively as this document goes to 'press'.

3.1 Some Findings

Harrison (1995) suggests that video and sound bytes be kept small, and that the steps which make up a procedure be kept small as well. She also notes that an audio clip of spoken instructions to match the written instructions on the screen can have a dramatic effect on accuracy. This concurs with Dilt's (1983) general recommendation to involve as many representational systems (senses) as possible.

Nielsen (1996) has observed that the way users browse hypertext documentation has an effect on how much content they are prepared to deal with at any particular level. He states that, on average, a user's reading speed from the screen is about 25% slower than from a printed page and recommends that the text content be reduced by 50% to compensate effectively for this. These findings also suggest that attention should be paid to the text sizes chosen for the display; screen resolutions are generally at least four times lower than that of a laser-printed page.

4 Future Work

With a large body of technical documentation comprising text, photo, audio and video components, the issues of versioning become more complex than with traditional, monolithic documents. Moeller (1995) has identified some of the issues that arise and shows that configuration management akin to that used for large software suites is indicated in large multimedia documentation suites.

The new communication issues for technical documentation are only part of the larger issue of how technology is inevitably requiring its creators and users to alter the way they interact with it and each other. We can only hope to escape the proverbial 'software tar pit' when the work practices and paradigms used by development teams make the same sort of quantum shift that hardware regularly goes through.

By changing radically the way we communicate information, we may be able also to pave the way for new approaches to work practices and increased efficiencies. In the future, it will be the way we go about our work that will determine whether technology serves us or enslaves us.

Bibliography

1
Dilts, R. (1983) Applications of Neuro Linguistic Programming, Meta Publications, California.

2
McLuhan, M. (1964) Understanding Media: The Extensions of Man, MIT Press, Massachusetts.

3
Harrison, S. M. (1995) A Comparison of Still, Animated, or Nonillustrated On-Line Help with Written or Spoken Instructions in a Graphical User Interface in Proceedings of CHI 95, Association of Computing Machinery
URL: http://www.acm.org/si chi/chi95/Electronic/documents/papers/smh_bdy.htm

4
Nielsen, J. (1996) Interface design for Sun's WWW site, Sun Microsystems
URL: http://www.sun.com:80/sun-on-net/uidesign/

5
Moeller, H. (1995) Versioning Structured Technical Documentation, University of Berlin
URL: http://cs-pub.bu.edu/students/ rads/dgd/workshop/moeller.html


Organised by: AUUG'96 & CSU Return to Conference Proceedings