Highly collaborative enterprises, including the major open source projects that constitute most hacker-created programs these days, basically run on documentation. Man pages and similar ephemera for such projects are often very good—by their own lights, and for their own purposes.
The catch is that that documentation is built by and for people involved with the collaborative community—insiders, in other words—and the informational needs of those people are often very different from those of end users. If you’re working with mature open source tools and you want to know if there’s a flag or a config file setting that mutates the tool’s behavior in a certain specific way, you’re covered. If you’re instead trying to familiarize yourself with the overall operation of the tool, or if you’re committing one of three dozen newbie mistakes and you want to know why, you’re more than likely hosed.
I don’t think “good” or “terrible” is really adequate to describe this dynamic (though it can be near-objectively good or terrible from certain user perspectives). It’s more a matter of priorities.
Highly collaborative enterprises, including the major open source projects that constitute most hacker-created programs these days, basically run on documentation. Man pages and similar ephemera for such projects are often very good—by their own lights, and for their own purposes.
The catch is that that documentation is built by and for people involved with the collaborative community—insiders, in other words—and the informational needs of those people are often very different from those of end users. If you’re working with mature open source tools and you want to know if there’s a flag or a config file setting that mutates the tool’s behavior in a certain specific way, you’re covered. If you’re instead trying to familiarize yourself with the overall operation of the tool, or if you’re committing one of three dozen newbie mistakes and you want to know why, you’re more than likely hosed.
I don’t think “good” or “terrible” is really adequate to describe this dynamic (though it can be near-objectively good or terrible from certain user perspectives). It’s more a matter of priorities.