= 27d567bc2d48d9f40e9ccc20ea370b15)
Jiro comments on Learned Blankness - Less Wrong
You are viewing a comment permalink. View the original post to see all comments and the full post content.
= 783df68a0f980790206b9ea87794c5b6)
Loading…= b715d02e85f7b3b4ae65ca3d3e450868)
Subscribe to RSS Feed
Powered by Reddit
= f037147d6e6c911a85753b9abdedda8d)
You are viewing a comment permalink. View the original post to see all comments and the full post content.
Comments (186)
It's my experience that manuals for a lot of hacker-created programs are horrible. Such programs are coded by people for their own needs, and documentation rarely serves their own needs--it's not necessary to explain what to do since anything they coded themselves they pretty much know how to use already, and if they coded for the joy in solving a puzzle, writing documentation is just work.
Such programs have awful UIs for very similar reasons.
There's also a big difference between a manual full of random, poorly organized, information and one that's really useful. A poorly organized manual serves the purposes of the hackers because it lets the hackers call people idiots for not looking in the manual regardless of how difficult the information is to find in it.
Many cries of RTFM are only a half-acknowledgment that manuals are good--manuals are good as tools to use against pesky non-hackers who find your program impenetrable, but manuals are not things that the hacker who cries out RTFM cares to improve.
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.