unix documentation

[utzoo!decvax!ucbvax!mhtsa!ihnss!cbosg!harpo!ber]

The ld:file.o:bad magic number is not a particularly good example of
the problems with documentation.
A quick look at the source pinpoints the error.
It occurs in a straight forward routine which reads the header of a file.
It indicates that the magic number is not recognized.  What should it say?
Perhaps there should be printed a small document decsribing what magic numbers
mean and how they are used in conjuction with the loader each time
this error arises.  As a matter of fact it could print the ld manual page
and the a.out manual page which ld references.  Where does it end?
I don't want to read it each time I get this error.

Looking at the source is NOT absolutely wrong because:

1) I think users SHOULD know the structure of their installation.  This
   includes the location of documents, binaries, SOURCES, libraries, games,
   etc.  It depends on how someone wants to use the system.  If they
   are going to write programs, they should understand what programs are and
   what they mean.  They should be encouraged to comprehend the basics
   of the steps involved in making a program do something.

2) Asking someone to look at a program's source does not violate any
   principles of unix programming.  True, a program should do something
   reasonable regardless of input.  But if it doesn't, what are you going
   to do?  Avoid or fix are the only possibilities.  So if you don't
   want to avoid it, take a look.

3) Yes i HAVE looked at /usr/src/cmd/ld/ld.vax.c. Give ME a break.

No, I don't feel all complaints of this sort are hot air.
Neither, I suspect, do the "dozens".  But finding fault with some particular
piece of code is not an argument for the condemnation of unix.  If the point is
to improve that code, fine.  By the way.  Staying out of your office to avoid
questions is merely denying people the privilage of understanding.  There
will ALWAYS be questions, and how you deal with them will affect how people
grow.

By insisting that the behavior and documentation of something "make sense"
may well be restrictive.  To whom must it make sense?  Must it not exist
if it doesn't make sense?
I think the point here is that there are different types
of people wanting/expecting different things from a system.  To reiterate,
I don't want to use a system which is tailored to the lowest denominator.
[If the road signs are too high maybe you're on the wrong road.]