52 Documentation? Mail version SMI 4.0 Sat Apr 9 01:54:23 PDT 1988 Type ? for help. "/usr/spool/mail/chris": 3 messages 3 new N 1 chris Thu Dec 22 15:49 19/643 editor saved “trash1” N 2 root Tue Jan 3 10:35 19/636 editor saved “trash1” N 3 chris Tue Jan 3 14:40 19/656 editor saved “/tmp/ma8” & ? Unknown command: "?" & What production environment, especially one that is old enough to drive, vote, and drink 3.2 beers, should reject the very commands that it tells you to enter? Why does the user guide bear no relationship to reality? Why do the commands have cryptic names that have no bearing on their function? We don’t know what Heiny’s problem was like a few others we’ve men- tioned in this chapter, his bug seems to be fixed now. Or perhaps it just moved to a different application. Date: Tuesday, September 29, 1992 7:47PM From: Mark Lottor mkl@nw.com To: UNIX-HATERS Subject: no comments needed fs2# add_client usage: add_client [options] clients add_client -i|-p [options] [clients] -i interactive mode - invoke full-screen mode [other options deleted for clarity] fs2# add_client -i Interactive mode uses no command line arguments How to Get Real Documentation Actually, the best form of Unix documentation is frequently running the strings command over a program’s object code. Using strings, you can get a complete list of the program’s hard-coded file name, environment vari- ables, undocumented options, obscure error messages, and so forth. For example, if you want to find out where the cpp program searches for #include files, you are much better off using strings than man: next% man cpp No manual entry for cpp. next% strings /lib/cpp | grep /

For Programmers, Not Users 53 /lib/cpp /lib/ /usr/local/lib/ /cpp next% Hmm… Excuse us for one second: % ls /lib cpp* gcrt0.o libsys_s.a cpp-precomp* i386/ m68k/ crt0.o libsys_p.a posixcrt0.o next% strings /lib/cpp-precomp | grep / /*%s*/ //%s /usr/local/include /NextDeveloper/Headers /NextDeveloper/Headers/ansi /NextDeveloper/Headers/bsd /LocalDeveloper/Headers /LocalDeveloper/Headers/ansi /LocalDeveloper/Headers/bsd /NextDeveloper/2.0CompatibleHeaders %s/%s /lib/%s/specs next% Silly us. NEXTSTEP’s /lib/cpp calls /lib/cpp-precomp. You won’t find that documented on the man page either: next% man cpp-precomp No manual entry for cpp-precomp. For Programmers, Not Users Don’t blame Ken and Dennis for the sorry state of Unix documentation today. When the documentation framework was laid down, standards for documentation that were prevalent in the rest of the computer industry didn’t apply. Traps, bugs, and potential pitfalls were documented more fre- quently than features because the people who read the documents were, for the most part, the people who were developing the system. For many of these developers, the real function of Unix’s “man” pages was as a place to collect bug reports. The notion that Unix documentation is for naive, or merely inexpert users, programmers, and system administrators is a recent