Re: Documentation has always been iffy for unix system APIs @boltar
It depends how far back you go.
If you look at the UNIX Version/Edition 7 man pages (admittedly much simpler than modern UNIXes), then they documented the behaviour of the system much more completely.
More recently (last thirty years or so), features have been added and copied to each UNIX (often reimplemented from another UNIX) implementation without the correct emphasis on the documentation. And don't get me started on the appalling state of Linux documentation, especially the complete abortion that is the man page/info system that appears to suggest that the documentation has been written, when in many cases, it hasn't.
Only yesterday, I realised that the both the AIX and Linux man page for tail do not include in either the prototype or the description the tail -200 filename type operation (it's deemed obsolete in POSIX V2, but still works, and I've been using it without thinking for 30+ years). This obsolete use is described in the Linux Info article on tail invocation, but not in the man page (RHEL 6.5).
What books allow are practical examples of how an interface is used, so that (lazy) programmers can crib other people's work without having to find out for themselves.
Not that I think that is a bad idea! I think that a lazy streak (of the right kind) is an essential feature of a good programmer or system admin. It encourages finding out how to do things efficiently, saving time and effort later.