Society for Technical Communication—Israel Chapter
Maxims of User Documentation: Lessons from the Past Twenty Years
 
by Edmond H. Weiss, Ph.D
  

 

Probably, 1980 was the year when User Documentation emerged from technical writing as a distinct specialty-perhaps even a new profession. In that year, Technical Communication, the journal of STC, offered a special issue on the subject, edited and written by IBMers, filled with such new constructs as usability and task-orientation.

Perhaps this would be a good time to reflect on the past twenty years or so, to discuss what the industry and profession have learned-or stubbornly failed to learn.

Maxim 1: But for feature-richness, User Documentation would have vanished by now.

Because the profession began with hardware writers, and because hardware is far less communicative than software, the old expectation was that all products would need documentation, lots of it. But what became clear by the end of the 80s was that user documentation, especially software documentation, was mainly an attempt to complete or supplement incomplete or inadequate interface design-that changes in the interface of the product could eliminate or reduce most documentation. At first, that entailed making things menu-driven and adding context-sensitive Help. Later it meant embedding information directly into a graphical interface, so that most users rarely consulted either manuals or Help.

What has prevented user documentation from disappearing, though, is the rage to add hundreds or thousands of new features to each software release. Despite the official industry propaganda about usability, it is obvious that feature-richness sells more products than ease of use. (Complexity=Unreliability.) Further, the rush to deliver under-tested, feature-rich products to market means that most interfaces are buggy, unreliable, and un-intuitive. This explains manuals the size of telephone directories in support of ordinary business applications. And it might explain the Help utility in Office 2000-except that there is no explanation for that strange creation. As has always been true, then, users consult documentation when the system has failed or frustrated them. Is it any wonder that Paul Somerson observed that:" Nobody likes manuals. Fact is, every intelligent user loathes them." Whenever the need for external documentation can be eliminated, it should be. Whenever the need for online or embedded Help can be eliminated, it should be.

Maxim 2: Technical publications should not be the work of Authors.

No matter how talented the writer, manuals and other documents should be a corporate project, not the work of a single author. All technical publications-especially Users' Manuals-are in a perpetual state of re-evaluation, update, and revision. Manuals written entirely by one person are inherently unmaintainable; that is, no one but the "author" understands the logic and content, so that others are unable to test and modify the publication during the life of its use.

Similarly, publications tested by their authors are full of bugs. When a document is an artistic product from a solitary, skilled artisan, that artisan is unwilling and unable to find and correct its flaws.

Maxim 3: Most User Documentation should be assembled, not authored.

In 1980, no one was quite sure how to create a useful, readable manual. By the early 90s, though, the problem was mainly solved. Any company publishing unsuitable documentation these days simply hasn't been paying attention.

Today, 90% of user documentation-paper or online-should be written by filling in the blanks of templates and wizards. Indeed, the move toward single-source documentation (which I predicted in the early 80s) reduces "writers" to compilers and assemblers of information. In many places these days, the job of the technical communicator is feeding modules into a document database. Is such documentation as good as the old-fashioned kind, which was fashioned by an imaginative and inventive writer, who took pride of authorship? Probably not. But the differences are largely irrelevant in the context that defines most user documentation. Which leads to .

Maxim 4: Every documentation question is a business question.

Every documentation decision hangs from the question: How's Business?

The "right" way to document or support technology products is determined by the needs of business, not some set of arbitrary writing standards. Those of us who love language and books, who spent a career mastering the art of the sentence . we must remember why these publications are produced and who pays our bills. We must, for obvious reasons, distance ourselves from documentation that does not add to the competitive advantage of our products and systems, documentation that costs more than it saves or earns. There are practical consequences to all these observations. To stay abreast of the times, technical communicators need to learn about:

  • Testing for usability, in both publications and interface design Implementing modularity and collaborative writing processes Developing document databases and applying single-source technology
  • Writing proposals and business cases, in support of documentation policies and technology.

 
   
Contact Us | Disclaimer | Sponsors | Home                                                                                                        Top
© 2006 The Society for Technical Communication—Israel Chapter