5 ms·

The site has enabled software vendors to slack off on their documentation ... I'm thinking of msdn as an example The number of questions on SO that can be answ

The site has enabled software vendors to slack off on their documentation ... I'm thinking of msdn as an example The number of questions on SO that can be answered by RTFM is quite remarkable. I think that points to a lot of the documentation being just fine. The last bug of my own I spent any significant of time on was answerable by RTFM [1]. There are plenty of PHP+MySQL questions that appear where the OP is clearly learning about PHP+MySQL and the code looks something like... $result = mysql_query("select username, password from user where username = " . $username) ...shows that they haven't bothered to RTFM [2]. [1] I had made a new thread and was calling ShellExecute on it. It didn't work on some computers because I hadn't initialised COM (presumably they had some shell extensions installed). See the first sentence of "Remarks" http://msdn.microsoft.com/en-us/library/windows/desktop/bb762153(v=vs.85).aspx http://msdn.microsoft.com/en-us/library/windows/desktop/bb76... [2] Big red box: http://www.php.net/mysql_query http://www.php.net/mysql_query

ritchiea 13y ago
I want to float a different hypothesis: the perception of programming is so hung up on the idea of individual brilliance that most people, especially beginners, don't even realize how much value there is in reading the manual. And we as programmers add to the problem. It's not very sexy to say that there is a lot of useful software out there written and documented by smart people and if you read that documentation, and think through a problem with great analytical detail you should be able to find a clear solution.
- ep103 13y ago
  My experience has been that technet's documentation is so unreliable that I've learned to go to SO first.
  - doorhammer 13y ago
    Yeah, I goto SO (well, SO through google) because with most questions, I get a practical answer to my exact situation in seconds, as well as suggestions as to why or why not different approaches might be warranted. They're not all perfect, but it's usually food for thought.
bottled_poe 13y ago
You are quite right. All of the information is in the manual, and if only everyone would spend their time reading the manual there wouldn't be so many questions on SO. However, the volume of information in most manuals is also the problem. If everyone read the whole manual, a lot of time would be collectively wasted because most of the information is not useful or relevant to what each individual developer is trying to do. In my opinion manuals should be written in several tiers of detail. Admittedly, a lot of software developers already publish documentation this way and these basic questions still get submitted to SO.
chavesn 13y ago
Why do people assume that RTFM does not have a cost? In fact, it's probably higher than searching SO through Google. This is why I'm hugely in favor of even basic questions getting answers on SO.
- tjbiddle 13y ago
  Agreed - Especially when I'm working on some technology where I don't need/want to learn it completely and just can't spare the time, but just need to know a small bit of information to fix some legacy item, or something similar. SO is invaluable there - but I do hate when I'm "that guy".
- mkartic 13y ago
  very well put. Both obscure and implicit/obvious information can be very hard to find by just reading the manual. (Aside from above) I love Python. I only know enough to get by though. I have this program that runs for a really long time, storing the results of each iteration in a dict. These results are complex python objects, and are meant to be processed later on. Naturally, I tried pickling them. As the file grew, Pickle quickly became cumbersome. It was a bad idea to read and write something that big every iteration. I started wondering if there was some way to write pickle objects incrementally. Then googled it, and an answer from SO led me to the 'shelve' module. It does exactly that, pickling objects incrementally. Its part of Python's standard library. But it didn't turn up on the first page of google's results. It is described in the docs as a 'persistent, dictionary-like object'. Well, if not for SO, I would have been stuck with the wrong set of keywords to search with. So, my point is, even if things ARE in the manual, it takes some effort finding it. And SO does an excellent job of leading you on to the right places in the manual/reference rather than just looking down upon you for not grokking the entire manual.
  - derleth 13y ago
    > Well, if not for SO, I would have been stuck with the wrong set of keywords to search with. This is precisely the sort of bootstrap problem good tutorials are meant to help you avoid. Learning out of a book is not as satisfying as grabbing an interpreter and some example code and just hacking away, but this is precisely a case where the by-the-book method can save you a lot of time and frustration later on. Another example of a problem tutorials solve is not knowing what 'tasteful' means in a given language. If you don't know what the language culture considers good taste, you'll beat your head against a wall trying to solve problems tasteful developers don't even have, because you're cutting against the grain. (Yes, yes, a Real Programmer can write FORTRAN-IV in any language.)
RandallBrown 13y ago
StackOverflow is just the manual in an easily searchable form. Lots of times I'm not even sure of what to even look up and that's when I post to StackOverflow. The next time someone else tries to do something similar, Google will have found it in StackOverflow and it will be easily found.
- brc 13y ago
  Easily searchable and constantly updated form. And free of vendor BS, too.
  - scotty79 13y ago
    Also has only the information people are actually interested in.
  - rbobby 13y ago
    Your comment has been closed because it has been deemed to be unsuitable for our question and answer format. And you're a bad person for asking!
sebkomianos 13y ago
Not everyone learns from manuals though.
zxcvvcxz 13y ago
> The number of questions on SO that can be answered by RTFM is quite remarkable. I think that points to a lot of the documentation being just fine. Actually that must point to the opposite: that manuals are not information resources that are easily consumable, and hence a new service (Stackoverflow and co.) needed to be developed to "disrupt" this. The more questions the better IMO, it's just more of a wealth of data to search through and serve to people. I wish there were better ways of asking more general questions that one just has no idea though (e.g. "How can I send SMS messages from a web site?" Random example of which I have no clue). These are more open-ended, but provide a ton of value. At the very least, they make googling for such things that much easier and direct.
nathan_long 13y ago
If you're stringing together a Unix pipe command, TFM might be for, say, awk. Would you rather stop what you're thinking about for 10 minutes and shave that yak, or get a quick answer and move on?
- acdha 13y ago
  There's another cost to consider: if you do this more than infrequently, learning the tools will save more time than consulting SO repeatedly — particularly if you end up adding and debugging extra steps. Not a big deal for something you're running once but I've seen people running carefully constructed gargantuan shell pipelines multiple times a day because it was "too hard" to learn how to do it all in a single awk / perl step
  - nathan_long 13y ago
    Agreed. But there are yaks you shave but once.
ako 13y ago
The more information is available in the documentation, the more you can benefit from somebody pointing you to the right information for your question. So I think that if software vendors were to document even more, you would need something like stack overflow even more. And then there's also the problem of cross-technology questions, where you have a question of combining multiple technologies. These kind of questions are usually a bad fit for documentation.
derleth 13y ago
> The number of questions on SO that can be answered by RTFM is quite remarkable. Every language needs two manuals: A reference text, to teach you what is possible, and a tutorial, to teach you what is tasteful. You should expect people to read the tutorial, but expecting everyone to inhale reference material is a bit much. (Later, there should be a third book: An anti-tutorial, laying out anti-patterns, or things you shouldn't be doing but that people tend to do anyway, and how to solve the problem the right way, with pointers to other tools if necessary.)

ritchiea 13y ago

I want to float a different hypothesis: the perception of programming is so hung up on the idea of individual brilliance that most people, especially beginners, don't even realize how much value there is in reading the manual. And we as programmers add to the problem. It's not very sexy to say that there is a lot of useful software out there written and documented by smart people and if you read that documentation, and think through a problem with great analytical detail you should be able to find a clear solution.

ep103 13y ago
My experience has been that technet's documentation is so unreliable that I've learned to go to SO first.
- doorhammer 13y ago
  Yeah, I goto SO (well, SO through google) because with most questions, I get a practical answer to my exact situation in seconds, as well as suggestions as to why or why not different approaches might be warranted. They're not all perfect, but it's usually food for thought.

bottled_poe 13y ago

You are quite right. All of the information is in the manual, and if only everyone would spend their time reading the manual there wouldn't be so many questions on SO. However, the volume of information in most manuals is also the problem. If everyone read the whole manual, a lot of time would be collectively wasted because most of the information is not useful or relevant to what each individual developer is trying to do. In my opinion manuals should be written in several tiers of detail. Admittedly, a lot of software developers already publish documentation this way and these basic questions still get submitted to SO.

chavesn 13y ago

Why do people assume that RTFM does not have a cost? In fact, it's probably higher than searching SO through Google. This is why I'm hugely in favor of even basic questions getting answers on SO.

tjbiddle 13y ago
Agreed - Especially when I'm working on some technology where I don't need/want to learn it completely and just can't spare the time, but just need to know a small bit of information to fix some legacy item, or something similar. SO is invaluable there - but I do hate when I'm "that guy".
mkartic 13y ago
very well put. Both obscure and implicit/obvious information can be very hard to find by just reading the manual. (Aside from above) I love Python. I only know enough to get by though. I have this program that runs for a really long time, storing the results of each iteration in a dict. These results are complex python objects, and are meant to be processed later on. Naturally, I tried pickling them. As the file grew, Pickle quickly became cumbersome. It was a bad idea to read and write something that big every iteration. I started wondering if there was some way to write pickle objects incrementally. Then googled it, and an answer from SO led me to the 'shelve' module. It does exactly that, pickling objects incrementally. Its part of Python's standard library. But it didn't turn up on the first page of google's results. It is described in the docs as a 'persistent, dictionary-like object'. Well, if not for SO, I would have been stuck with the wrong set of keywords to search with. So, my point is, even if things ARE in the manual, it takes some effort finding it. And SO does an excellent job of leading you on to the right places in the manual/reference rather than just looking down upon you for not grokking the entire manual.
- derleth 13y ago
  > Well, if not for SO, I would have been stuck with the wrong set of keywords to search with. This is precisely the sort of bootstrap problem good tutorials are meant to help you avoid. Learning out of a book is not as satisfying as grabbing an interpreter and some example code and just hacking away, but this is precisely a case where the by-the-book method can save you a lot of time and frustration later on. Another example of a problem tutorials solve is not knowing what 'tasteful' means in a given language. If you don't know what the language culture considers good taste, you'll beat your head against a wall trying to solve problems tasteful developers don't even have, because you're cutting against the grain. (Yes, yes, a Real Programmer can write FORTRAN-IV in any language.)

RandallBrown 13y ago

StackOverflow is just the manual in an easily searchable form. Lots of times I'm not even sure of what to even look up and that's when I post to StackOverflow. The next time someone else tries to do something similar, Google will have found it in StackOverflow and it will be easily found.

brc 13y ago
Easily searchable and constantly updated form. And free of vendor BS, too.
- scotty79 13y ago
  Also has only the information people are actually interested in.
- rbobby 13y ago
  Your comment has been closed because it has been deemed to be unsuitable for our question and answer format. And you're a bad person for asking!

sebkomianos 13y ago

Not everyone learns from manuals though.

zxcvvcxz 13y ago

> The number of questions on SO that can be answered by RTFM is quite remarkable. I think that points to a lot of the documentation being just fine. Actually that must point to the opposite: that manuals are not information resources that are easily consumable, and hence a new service (Stackoverflow and co.) needed to be developed to "disrupt" this. The more questions the better IMO, it's just more of a wealth of data to search through and serve to people. I wish there were better ways of asking more general questions that one just has no idea though (e.g. "How can I send SMS messages from a web site?" Random example of which I have no clue). These are more open-ended, but provide a ton of value. At the very least, they make googling for such things that much easier and direct.

nathan_long 13y ago

If you're stringing together a Unix pipe command, TFM might be for, say, awk. Would you rather stop what you're thinking about for 10 minutes and shave that yak, or get a quick answer and move on?

acdha 13y ago
There's another cost to consider: if you do this more than infrequently, learning the tools will save more time than consulting SO repeatedly — particularly if you end up adding and debugging extra steps. Not a big deal for something you're running once but I've seen people running carefully constructed gargantuan shell pipelines multiple times a day because it was "too hard" to learn how to do it all in a single awk / perl step
- nathan_long 13y ago
  Agreed. But there are yaks you shave but once.

ako 13y ago

The more information is available in the documentation, the more you can benefit from somebody pointing you to the right information for your question. So I think that if software vendors were to document even more, you would need something like stack overflow even more. And then there's also the problem of cross-technology questions, where you have a question of combining multiple technologies. These kind of questions are usually a bad fit for documentation.

derleth 13y ago

> The number of questions on SO that can be answered by RTFM is quite remarkable. Every language needs two manuals: A reference text, to teach you what is possible, and a tutorial, to teach you what is tasteful. You should expect people to read the tutorial, but expecting everyone to inhale reference material is a bit much. (Later, there should be a third book: An anti-tutorial, laying out anti-patterns, or things you shouldn't be doing but that people tend to do anyway, and how to solve the problem the right way, with pointers to other tools if necessary.)