For those of you who haven't upgraded to 3.2 yet, zgrep is a new program in /usr/bin that wasn't part of the 3.1 release. Unfortunately, those of you who have upgraded will discover that zgrep doesn't come with any documentation Ð NeXT has left us on our own. Being the adventurous hacker that I am, I bravely typed "zgrep" at the Terminal prompt and got this helpful message:
% zgrep
grep through gzip files
usage: zgrep [grep_options] pattern [files]
Oh, so that explains it: zgrep greps through gzip files. Fortunately, NEXTSTEP 3.2 includes on-line documentation for both grep and gzip. (The man page for gzip was somehow not included in NEXTSTEP 3.1.)
To be fair, NEXTSTEP 3.2 is, on the whole, better documented than 3.1 ever was. There are only 27 commands in the 3.2 /bin and /usr/bin directories for which NeXT didn't provide man pages (a substantial improvement over 3.1). Most of 3.2's mysteries, such as zgrep, are fairly obvious. NeXT has even started to document commands like lipo, which it wrote to support fat binaries. Unfortunately, the usage, options, and magical incantations needed for other new or arcane commands remain a mystery.
Any operating-system vendor can grab the latest utilities from the Free Software Foundation (FSF), throw the commands in /bin and their documentation into /usr/man, and call it a "state-of-the-art operating-system software." To NeXT's credit, the company's developers are actually making advancements in the underlying operating system as well (features like fat binaries and Driver Kit fall into this category). But unlike the FSF, which values documentation as highly as code development, NeXT seems to let documentation take a backseat to hacking.
I've raised the issue of documentation with NeXT many times in the past. According to Rick Jackson, NeXT's director of product marketing, the company can only allocate a certain amount of people to technical publications, "given NeXT's limited resources." NeXT has also specifically chosen not to document some aspects of its operating system, such as InterfaceBuilder's internal file format and the API for applications like Mail and ProjectBuilder, so that the company doesn't get locked into supporting developers who write code that requires particular file formats or object calls.
The flaw with this argument is that the FSF isn't exactly overflowing with cash itself, yet it manages to ship detailed and accurate documentation concurrently with its utilities and application programs.
The real difference between how NeXT and the FSF handle documentation is that NeXT views documentation as an afterthought, a nice-to-have, something that is fundamentally not as important as the underlying code. The FSF, on the other hand, views documentation as an essential ingredient in the product mix. You can't effectively use an application or an operating system unless you have clear, concise documentation that explains it.
There is a hidden benefit to good documentation. When programmers are forced to sit down, go through their code, and write about how it works, they frequently find bugs that were not uncovered during development or testing. Perhaps this is one of the reasons why the FSF generally produces more reliable code than the hackers in Redwood City.
Simson L. Garfinkel is the senior contributing editor to NeXTWORLD.