informativeMedia - If nobody reads the manual ...

Advanced users know the truth about a software application. They have practical experience of a current product, its previous versions, or competing products. They can see behind the gloss of phrases dreamt up by the marketing department. Advanced users recognise an application's special "features" for what they really are—inadequate or incomplete software design and implementation. These people want to know:

These types of information are typically missing from the manuals supplied by software publishers. In a competitive market, it does not pay to publicise the limitations of a product, and, anyway, some of the weak points are not identified until after the product is released. Also, within the constraints of a development project, there is rarely time to identify or investigate all the creative uses that users might find for a product.

It is far easier to publish a manual that meets the wishes of advanced users after an application goes on the market. However, I am not aware of any software publisher that distributes follow-up manuals after an application has been released. So here we have an opportunity for book publishers to exploit. The writers of some advanced-level books have useful relationships with the companies producing the software they write about. In such cases, the writers usually acknowledge having received help and encouragement from product managers or developers. Clearly, the development organisation sees the relationship with the writers as being mutually advantageous. A writer who has made the effort to become an expert in a particular product is almost certainly a fan of that product. The software publisher therefore sees the writer as an ideal ambassador for the software—an ambassador who is likely to be even more complimentary about the product if given a helping hand.

Because the manual is insufficient

When you buy a Microsoft product, you get a small amount of printed documentation. Yet at the same time, Microsoft Press probably offer you several books on the same product. Clearly some software publishers, and Microsoft is just one very obvious example, have decided to generate some extra revenue by branching into the book-publishing business. Of course, Microsoft applications come with online help and other forms of electronic information. And it is only right that I point out that Microsoft has taken a leading role in promoting and improving ways of integrating user assistance into software. Nonetheless, some users want printed information, and Microsoft seem increasing unwilling to provide it for free.

Let me give a specific example from my bookshelf. When I bought Microsoft's Visual Basic 6.0, it came with one slim manual of 218 pages. After just three introductory pages, the remainder of the manual consists of "selected chapters" from three books published by Microsoft Press. Just in case this advertising is too subtle, the back cover of the manual reminds readers about the three books that contributed to "this sampler"—because that is evidently the way that Microsoft views the manual. It seems that Microsoft felt that those 218 pages in the manual represented enough information to fulfil its legal or moral obligations to its customers even though it clearly had further useful information available.

My previous paragraph is not necessarily a criticism of Microsoft's strategy. I'm sure that many software buyers would be happy to choose—and pay for—books geared to their individual needs, rather than receive a generic set of "free" manuals, if the software was cheaper as a consequence. And certainly, for many products, Microsoft Press offers a comprehensive selection of books to suit all levels of competence. However, are those prices falling as the manuals get thinner?

I have mentioned Microsoft, but they are by no means alone. Over the last few years, I have noticed other software publishers selling books about their products. This practice of giving away some information with a product and then selling other information is not new. In the past, the sold information was generally in the form of instructor-led training. However, some companies have a policy of giving away standard manuals but charging for more specialised manuals.

Because users want better tutorials

Many applications provide some form of tutorial. In some cases, it takes the form of an interactive, multimedia experience provided on a CD-ROM or even built into the application itself. More often, it comes in the form of a slim manual or as part of a larger manual. Many of these paper tutorials encourage readers to spend an hour or two being led, step-by-step, through an application's principal features. This may help some readers get an overview of an application, but this type of tutorial tends to follow a simple path that avoids the problems and complications typical of real work situations. I often wonder about the true educational value of some of these tutorials; readers have to interact physically with the application, but do the tutorials really engage their minds? Another problem with simple tutorials is that they tend to treat one application in isolation. In true working environments, users often use several applications together.

Many commercial computing books are essentially longer, more complex tutorials. They cover one or more substantial projects that are a better reflection of the type of work that readers will want to accomplish. Although a book may focus on one main application, its tutorial projects often requires readers to use other applications as well; these additional applications are often provided on a CD-ROM that accompanies the book. The result is a richer learning experience—though, admittedly, a more time-consuming one. It seems that plenty of people are prepared to find the time and money for this type of book. (I own a few myself.)

Consequences for technical authors

As I have suggested already, people buy software books for many reasons. At least some buyers have examined the manuals supplied with an application and have decided that they are better served by a book. This is rather predictable. Authors' manuals are always a compromise, shaped by factors such as the need to:

Writers have the privilege of being able to focus on just a portion of an application's users and to explain only the features that interest these people. It is therefore no surprise that some readers will feel that a particular book meets their needs perfectly. However, we cannot say that writers do a better job than authors because the two groups are working to different agendas, driven by different pressures. Writers rarely have to consider issues such as translation and publishing in multiple formats.

Software books are usually printed in colour with eye-catching covers, stylish page layouts, and plenty of graphic elements scattered throughout the pages. This is clearly necessary in a competitive market where buyers often make choices in a few moments and often on fairly superficial criteria. Technical authors will argue that attractive packaging does not make a document more useful. However, books do put a certain pressure on technical authors to provide similar levels of presentation. If a manual looks old-fashioned, the product seems out-of-date by inference.

Market trends in books are likely to influence what employers and clients expect to see in manuals. So technical communicators need to understand what publishers are offering. I can give a specific example. O'Reilly has built up a solid reputation as a publisher of books that will please even the most critical coder. In the eyes of one of my clients, they epitomise quality documentation to the extent that he asked for page layouts and typological conventions "like O'Reilly books". This request presented no problem because there is nothing revolutionary about O'Reilly computing books; they reflect the ideas that most technical authors know, accept, and regularly put into practice. And, reassuringly, O'Reilly thrives by following the principle that good content is more important than flashy presentation.

As I mentioned earlier, some software companies limit the information they give away free with software because they retain and use other information to generate additional revenue. Unfortunately, some managers (especially if they have little experience of technical communication) are likely to look at the slim manuals for Microsoft product and think,"If it's good enough for them, it's good enough for our product". To prevent such a manager making an ill-informed decision, technical authors need to be able to explain that a small manual is often just one part of an overall user-assistance strategy that includes, for example, commercial books, consulting services, and partnerships with training companies.

Overall, the existence of so many commercial computing books is rather reassuring for technical authors. It confirms our belief that people really do need and want explanations. Too many of our technical colleagues are so familiar with technology that they consider all application software to be "intuitive"—one of the most over-used words in computing. Anyone who takes the time away from a technical work environment soon learns that some seemingly competent users have strange ideas about how computers and software work. Also most users seem to work inefficiently with software, mastering just a minor fraction of the available features. So, as technical authors, we must fight the temptation to get sucked into adopting the mind-set of our technical colleagues, even though we work beside them every day. Users really do need assistance.

If nobody reads the manual ...

… why are bookshops overflowing with computing books?

Because advanced users want to know more

Because the manual is insufficient

Because users want better tutorials

Consequences for technical authors