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.

56 Documentation? Unix Without Words: A Course Proposal Date: Fri, 24 Apr 92 12:58:28 PST From: cj@eno.corp.sgi.com (C J Silverio) Organization: SGI TechPubs Newsgroups: talk.bizarre1 Subject: Unix Without Words [During one particularly vitriolic flame war about the uselessness of documentation, I wrote the following proposal. I never posted it, because I am a coward… I finally post it here, for your edification.] Unix Ohne Worter Well! I’ve been completely convinced by the arguments presented here on the uselessness of documentation. In fact, I’ve become con- vinced that documentation is a drug, and that my dependence on it is artificial. I can overcome my addiction, with professional help. And what’s more, I feel morally obliged to cease peddling this useless drug for a living. I’ve decided to go back to math grad school to reeducate myself, and get out of this parasitic profession. Perhaps it just reveals the depth of my addiction to documentation, but I do see the need for SGI to ship one document with our next release. I see this book as transitional only. We can eliminate it for the following release. Here’s my proposal: TITLE: “Unix Without Words” AUDIENCE: The Unix novice. OVERVIEW: Gives a general strategy for approaching Unix without documentation. Presents generalizable principles useful for deciphering any operating system without the crutch of documentation. CONTENTS: 1Forwarded to UNIX-HATERS by Judy Anderson.