ugh.book

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.