Documentation and the Future of UNIX

by Tim O'Reilly
October 1984

Countless computer industry analysts have hailed the UNIX operating system as the wave of the future. Almost as many others have criticized it as unwieldy, unfriendly, and unlikely to succeed.

Whatever the eventual outcome of the debate, no one can contest the fact that there is hardly a computer manufacturer in America that does not have at least a token UNIX offering. Many companies have staked their s urvival on the acceptance of this brainchild of Bell Laboratories as an operating system standard. AT&T of course has made UNIX a major part of their computer strategy, and IBM, at least partly in response to AT&T, has made several UNIX offerings, ranging from PC-IX and Xenix on the PC-XT to VM-IX on its mainframes. Countless "supermicro" vendors--including Bay State companies such as Masscomp, Charles River Data Systems, and Pixel Systems--are shipping powerful UNIX-based machines. There are even numerous versions of UNIX for personal computers, most notably Microsoft's Xenix, Interactive Systems' PC-IX, and Venturcom's Venix. Those who do not currently have UNIX offerings are waiting in the wings.

There are several interconnected factors that have made UNIX the focus of so much activity.

First, and most importantly, UNIX offers at least the promise of an industry-wide operating system standard. An operating system is the foundation for other computer software, and acts as a translator between the application program, which does the jobs the end user really wants done, and the computer hardware.

An industry-standard operating system will mean that software need not be developed and sold for a particular machine, but will be easily adaptable to many different machines. While this may harm the development of proprietary software by computer hardware manufacturers, it is a tremendous boon to independent software vendors and end users. As the cost of computer hardware decreases, software costs take up a larger and larger part of the total computer system cost. And unlike hardware, which always makes up a fixed part of the manufacturing cost of the machine, software is almost entirely a development cost. It can therefore benefit enormously from economies of scale.

No one questions that the enormous success of software companies such as Lotus Development Corp. is based on the microcomputer explosion that created a target market of millions of machines, and allowed powerful software to be sold for a few hundred dollars instead of tens of thousands. What the dominance of IBM and IBM compatible machines using the MS-DOS operating system did for the microcomputer industry, UNIX promises to do for the computer industry as a whole.

Second, UNIX is a general purpose time-sharing multi-tasking operating system. That is, it allows several people to use a computer at the same time, and what's more, for each user to do several different jobs at the same time. There is considerable pressure from the microcomputer segment for just these capabilities. In addition to lovering the cost per user, a multi-user system makes it easier for people to share data and work jointly on large projects. Capability in computers is addicting. The more users can do, the more they want to do.

UNIX is the only serious multi-user system that is not tied to a particular manufacturer's hardware. It thus provides an upgrade path to frustrated microcomputer users who want more power, but are not totally ready to abandon their old machines.

Third, UNIX provides a rich and versatile set of computer tools. It was originally developed by programmers at Bell Laboratories for their own use, then licensed at low cost to university computer science departments. It was designed as a flexible, easily extensible programming environment, and it has grown through the incremental additions of thousands of talented if sometimes undisciplined contributors. Because of the way it is designed, even relative computer novices find themselves creating new computer tools.

However, UNIX's strengths are also its weaknesses.

The advantage of an industry standard operating system for software developers may have exactly the opposite effect on hardware vendors. Deprived of a captive base of users locked into their hardware by proprietary software, they will be forced to compete on price, performance, and added value.

This development can be seen most clearly in the crowded supermicro marketplace, where hundreds of companies are struggling to differentiate themselves. Some (Westford's Masscomp comes to mind as a good example) have added value by adding special features to the UNIX operating system itself. (Masscomp developed a "Real Time UNIX" that is especially suited for scientific applications involving data acquisition and graphics).

Another step that must be taken by UNIX system manufacturers trying to make their mark is to make the many tools available under UNIX accessible to their user. This includes the development of windowing systems and other sophisticated user interface software. It also includes something decidedly low-tech: better printed books and manuals.

The UNIX documentation set grew like the system itself--randomly. This sometimes undisciplined growth has made UNIX a system of tremendous richness; it has also left it (at least on the surface) almost overwhelmingly complex. The subset of essential commands is no larger nor more complex than that of the microcomputer MS-DOS with which so many people are now familiar. However, UNIX users are faced with program names like awk (named for its authors, Aho, Weinberger, and Kernighan), and yacc (yet another compiler compiler), whose functions seem as obscure as their names.

To make the situation worse, there are numerous versions of UNIX, each slightly different. The difference between versions of UNIX is a particular problem because of the documentation traditionally provided with the system. The hundreds of available commands (and the literally thousands of command options) are listed in an enormous reference manual that is threatening to the new user simply because of its size. Further details on major utility commands are usually provided in technical papers written by the creator of the program and assembled into another enormous volume.

One condition of success in the UNIX marketplace is increasingly coming to be the quality of the documentation and training materials supplied with the system. In order to distinguish themselves from the competition, UNIX system developers need to provide their users with friendly, effective UNIX documentation that goes beyond the standard document set supplied by Bell Laboratories. Useful documents include an Introduction to UNIX, a UNIX System Management Guide, and a UNIX Quick Reference.

The first of these books should be directed at the first time user, and should contain a walkthrough of the most common features of the UNIX operating system, with an emphasis on what is distinctive about the manufacturer's own implementation or product emphasis. There are now a number of good introductions to UNIX available in most bookstores. However, even the best of these books suffers from the differences between UNIX systems. While they present a good overview, they often must trail off at critical points with the remark: "What you see may be slightly different on your system." When it comes to issues like using removable media like floppies, or the details of system management, a generic text simply cannot supply the level of fine detail that the user needs to actually do many things.

A UNIX System Management Guide should cover those issues that until now have been the province only of UNIX system "gurus": adding users, creating and maintaining file systems, supporting additional terminals and other peripherals basic system configuration, system backup and restore, and error handling. Much of this information simply cannot be presented in a generic book, since the "magic numbers" that must be passed to the system processes involved vary from system to system and from configuration to configuration.

A UNIX Quick Reference supplements the standard UNIX Reference Manual (or UNIX Programmer's Guide, as it is sometimes called) with a pocket-sized quick reference that contains a concise listing and explanation of all available options to each command. Because of the richness of the UNIX system, even the most experienced user often has a need to look up some of the more obscure options and commands. While a Quick Reference can't entirely supplant the standard UNIX Reference Manual, it can replace as many as 90% of user references to that manual.

Additional manuals that can be attempted by those who are truly stout of heart include a Guide to Writing a UNIX Device Driver and a system-specific UNIX Programming Manual.

Tim O'Reilly is the president of O'Reilly & Associates, Inc. (ORA), a Newton, Mass. consulting firm specializing in technical documentation. ORA writes manuals for high-tech clients, and also licenses a line of UNIX manuals that can be customized for special implementations of UNIX.