54 Documentation? invention. Sadly, it hasn’t been very successful because of the underlying Unix documentation model established in the mid 1970s. The Unix world acknowledges, but it does not apologize for, this sorry state of affairs. Life with Unix states the Unix attitude toward documenta- tion rather matter-of-factly: The best documentation is the UNIX source. After all, this is what the system uses for documentation when it decides what to do next! The manuals paraphrase the source code, often having been written at different times and by different people than who wrote the code. Think of them as guidelines. Sometimes they are more like wishes… Nonetheless, it is all too common to turn to the source and find options and behaviors that are not documented in the manual. Some- times you find options described in the manual that are unimple- mented and ignored by the source. And that’s for user programs. Inside the kernel, things are much worse. Until very recently, there was simply no vendor-supplied documentation for writing new device drivers or other kernel-level functions. People joked “anyone needing documentation to the kernel functions probably shouldn’t be using them.” The real story was, in fact, far more sinister. The kernel was not docu- mented because AT&T was protecting this sacred code as a “trade secret.” Anyone who tried to write a book that described the Unix internals was courting a lawsuit. The Source Code Is the Documentation As fate would have it, AT&T’s plan backfired. In the absence of written documentation, the only way to get details about how the kernel or user commands worked was by looking at the source code. As a result, Unix sources were widely pirated during the operating system’s first 20 years. Consultants, programmers, and system administrators didn’t copy the source code because they wanted to compile it and then stamp out illegal Unix clones: they made their copies because they needed the source code for documentation. Copies of Unix source code filtered out of universities to neighboring high-tech companies. Sure it was illegal, but it was justifi- able felony: the documentation provided by the Unix vendors was simply not adequate.

For Programmers, Not Users 55 This is not to say that the source code contained worthwhile secrets. Any- one who had both access to the source code and the inclination to read it soon found themselves in for a rude surprise: /* You are not expected to understand this */ Although this comment originally appeared in the Unix V6 kernel source code, it could easily have applied to any of the original AT&T code, which was a nightmare of in-line hand-optimizations and micro hacks. Register variables with names like p, pp, and ppp being used for multitudes of dif- ferent purposes in different parts of a single function. Comments like “this function is recursive” as if recursion is a difficult-to-understand concept. The fact is, AT&T’s institutional attitude toward documentation for users and programmers was indicative of a sloppy attitude toward writing in gen- eral, and writing computer programs in particular. It’s easy to spot the work of a sloppy handyman: you’ll see paint over cracks, patch over patch, everything held together by chewing gum and duct tape. Face it: it takes thinking and real effort to re-design and build something over from scratch. Date: Thu, 17 May 90 14:43:28 -0700 From: David Chapman zvona@gang-of-four.stanford.edu To: UNIX-HATERS I love this. From man man: DIAGNOSTICS If you use the -M option, and name a directory that does not exist, the error message is somewhat misleading. Suppose the directory /usr/foo does not exist. If you type: man -M /usr/foo ls you get the error message “No manual entry for ls.” You should get an error message indicating that the directory /usr/foo does not exist. Writing this paragraph must have taken more work than fixing the bug would have.