I have a friend who was appalled that I suggested he read the manual before he tried to figure out how to fix his coffee machine by himself. I was appalled that he was appalled.
From what I can tell, this is flatly false. “RTFM” is a common catch phrase. Users are expected to familiarize themselves with available documentation in order to avoid making newbie mistakes. Tools coming out of advanced hacker cultures, such as the BSD community, tend to have excellent documentation.
I’ve even encountered hackerly tools with lock-outs to ensure that you’ve read the manual — for instance a command that defaults to doing nothing, and only does what it’s supposed to if you use a command-line switch only mentioned in the middle of the documentation. (In the case I’m thinking of, this was a safety feature on a tool that could be easily misused in a way that would harm others.)
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.
I’ve even encountered hackerly tools with lock-outs to ensure that you’ve read the manual
One way to do this is to not even put the dangerous options in the manual. For example, I often use wget to download static copies of websites (many of whose owners would prefer I not). The default way to block spiders like wget is to throw up a narrow robots.txt which wget will read and then abort; if you search the wget man page, there is no option to stop this. However, if you are an advanced user or you went as far as reading the default .wgetrc configuration file, you find something useful, and in my own file one will find the following:
# Setting this to off makes Wget not download /robots.txt. Be sure to
# know *exactly* what /robots.txt is and how it is used before changing
# the default!
robots = off
Of course, I do know exactly what robots.txt is, why ignoring it is potentially dangerous, and why I want to ignore it. So it all works out for me, and avoids noobs DoSing websites.
And no documentation serves as its own self-enforcing way of making sure only the technically skilled can use a program… Consider a tool I am using right now to investigate Bitcoin usage among torrent uploaders on The Pirate Bay: https://github.com/andronikov/tpb2csv This could use up a lot of bandwidth and hurt the TPB if someone were to use it wastefully and accidentally throw it in, say, a while loop. Fortunately (?), the repo has hardly any documentation, doesn’t tell you which file you would run (download.py), how (python download.py), what dependencies you need (python-requests python-beautifulsoup), what the arguments are (unique IDs embedded in the URLs of the relevant TPB torrent pages), or where you would get them (valid torrent IDs start in the 3m range and increment to the latest in http://thepiratebay.se/recent ).
Anyone who can figure all that out probably has a good reason for using the code and won’t abuse it.
Anyone who can figure all that out probably has a good reason for using the code and won’t abuse it.
I agree with the first part. After all, there are many people for which “stealing money” is their good reason for using poorly documented software tools, although this particular piece of code probably won’t help with that...
I can understand the DIY ethic that underlies rejection of fixed instructions, but it can result in unforeseen damage out of pointless rebelliousness. In Spanish we have a saying: Ignorance is insolent.
Being familiar with the manual should be the FIRST step in any troubleshooting process. If I were involved in hacking culture, I would move to change that cultural trait toward more sanity.
xkcd’s take on note 4.
I google the problem a lot sooner than the flowchart suggests.
I usually start with Google :)
I delay Google’ing to the last possible moment on purpose. It’s by figuring out stuff by yourself that you really learn :).
I guess I learn better from manuals than from random experimentation :)
I have a friend who was appalled that I suggested he read the manual before he tried to figure out how to fix his coffee machine by himself. I was appalled that he was appalled.
In hacker culture reading the manual is a shameful last-resort act of desperation...
From what I can tell, this is flatly false. “RTFM” is a common catch phrase. Users are expected to familiarize themselves with available documentation in order to avoid making newbie mistakes. Tools coming out of advanced hacker cultures, such as the BSD community, tend to have excellent documentation.
I’ve even encountered hackerly tools with lock-outs to ensure that you’ve read the manual — for instance a command that defaults to doing nothing, and only does what it’s supposed to if you use a command-line switch only mentioned in the middle of the documentation. (In the case I’m thinking of, this was a safety feature on a tool that could be easily misused in a way that would harm others.)
I’ve noticed that tools coming out of hacker culture often have terrible UI.
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.
One way to do this is to not even put the dangerous options in the manual. For example, I often use
wgetto download static copies of websites (many of whose owners would prefer I not). The default way to block spiders like wget is to throw up a narrowrobots.txtwhich wget will read and then abort; if you search the wget man page, there is no option to stop this. However, if you are an advanced user or you went as far as reading the default.wgetrcconfiguration file, you find something useful, and in my own file one will find the following:Of course, I do know exactly what robots.txt is, why ignoring it is potentially dangerous, and why I want to ignore it. So it all works out for me, and avoids noobs DoSing websites.
And no documentation serves as its own self-enforcing way of making sure only the technically skilled can use a program… Consider a tool I am using right now to investigate Bitcoin usage among torrent uploaders on The Pirate Bay: https://github.com/andronikov/tpb2csv This could use up a lot of bandwidth and hurt the TPB if someone were to use it wastefully and accidentally throw it in, say, a
whileloop. Fortunately (?), the repo has hardly any documentation, doesn’t tell you which file you would run (download.py), how (python download.py), what dependencies you need (python-requests python-beautifulsoup), what the arguments are (unique IDs embedded in the URLs of the relevant TPB torrent pages), or where you would get them (valid torrent IDs start in the 3m range and increment to the latest in http://thepiratebay.se/recent ).Anyone who can figure all that out probably has a good reason for using the code and won’t abuse it.
I agree with the first part. After all, there are many people for which “stealing money” is their good reason for using poorly documented software tools, although this particular piece of code probably won’t help with that...
It’s basically a script kiddie filter. Unfortunately it’s not very effective.
I think we’ll have to disagree about that.
Correct. Note, however, that in classic hacker culture “user” is one of the antonyms of “hacker” (“suit” is another one).
P.S. For full disclosure let me note that I’m not taking this subthread entirely seriously :-)
I can understand the DIY ethic that underlies rejection of fixed instructions, but it can result in unforeseen damage out of pointless rebelliousness. In Spanish we have a saying: Ignorance is insolent.
Being familiar with the manual should be the FIRST step in any troubleshooting process. If I were involved in hacking culture, I would move to change that cultural trait toward more sanity.
LOL.
Sanity is overrated.