4 ms·

The problem of writing documentation is that it's not possible to write it to suite every person. While most documentation certainly can be improved upon it's a

by amag 10y ago

The problem of writing documentation is that it's not possible to write it to suite every person. While most documentation certainly can be improved upon it's always the matter of where to best spend my time. Developing a feature or document an old feature in yet another way to serve people with a different mindset than my own. With the risk of sounding a bit of "it's programming it's meant to be hard", I feel the author is a bit spoiled. It's not as if the information wasn't there, she just needed ctrl-f "%r". This is also something you need to learn when learning how to program. In fact I would say that looking up information online is a fundamental programming skill (it didn't use to be, back in the days it was finding stuff in books, but we're mostly past that now, ctrl-f is so much nicer). So she just learned a very valuable lesson, I'd say.

jrumbut 10y ago
I agree with your take on documentation, and I agree that there are some difficult concepts even in basic programming that you just have to work hard to learn. Reading dense documentation is a programming skill, so it doesn't seem ridiculously out of bounds to be still in the process of learning it when on a programming education site. What I'm trying to say is more along the lines of "if you don't have anything nice to say don't say anything at all." Saying "oh hey try ctrl f on that documentation page you looked at" would be a valuable response, saying that asking the question is dumb isn't a positive contribution and is likely to make the asker defensive and unlikely to really learn from the experience.
- exolymph 10y ago
  >Saying "oh hey try ctrl f on that documentation page you looked at" would be a valuable response, saying that asking the question is dumb isn't a positive contribution and is likely to make the asker defensive and unlikely to really learn from the experience. 100% — this is the point I was trying to make
  - amag 10y ago
    I agree with the sentiment that being snarky doesn't help, but I think ddebernardy is correct when saying: "Sure, a good samaritan could do the work, figure it out, learn something new in the process, and answer. Maybe they'll even answer it another few times for the feel-good factor. But at some point they'll get bored or irritated, and therein lies the rub." Personally after having answered a lot of questions - in a nice, helpful way, mind you - questions whose answer could simply be "RTFM", these days I just avoid them. The problem with these kinds of questions are that more and more they offer nothing to the person answering them. A lot of them are asked by people who created an account on SO just to ask that question and then throws away the key (to that account). So don't expect to get any feedback, whether karma, comments or to be marked accepted. Don't expect there to be an interesting discussion with other devs with different experiences. I mean, I was answering questions on forums long before there was any karma involved just because I like to help/teach, but for that to be interesting to me who answers questions, there must be some sort of feedback. Karma is one way but I always preferred the good ol' discussion. It means I get to learn something as well. Questions answerable with "RTFM" offer very little of that. I guess what I'm saying is that people who answers question on SO (or similar sites) are not getting paid to answers those questions. They do it for fun, learning experience, karma, status or whatever. So there has to be something in it for them as well.
    - jrumbut 10y ago
      I like your approach, just move on if it's not what you want to do. That should be the general rule, and I think that's what most people do. The other benefit is that it leaves the door open to new participants, who are excited enough to know something that they don't mind not getting the upvote. Online communication is one of the most important skills to have, and every skill takes practice.

by amag 10y ago

jrumbut 10y ago

I agree with your take on documentation, and I agree that there are some difficult concepts even in basic programming that you just have to work hard to learn. Reading dense documentation is a programming skill, so it doesn't seem ridiculously out of bounds to be still in the process of learning it when on a programming education site. What I'm trying to say is more along the lines of "if you don't have anything nice to say don't say anything at all." Saying "oh hey try ctrl f on that documentation page you looked at" would be a valuable response, saying that asking the question is dumb isn't a positive contribution and is likely to make the asker defensive and unlikely to really learn from the experience.

exolymph 10y ago
>Saying "oh hey try ctrl f on that documentation page you looked at" would be a valuable response, saying that asking the question is dumb isn't a positive contribution and is likely to make the asker defensive and unlikely to really learn from the experience. 100% — this is the point I was trying to make
- amag 10y ago
  I agree with the sentiment that being snarky doesn't help, but I think ddebernardy is correct when saying: "Sure, a good samaritan could do the work, figure it out, learn something new in the process, and answer. Maybe they'll even answer it another few times for the feel-good factor. But at some point they'll get bored or irritated, and therein lies the rub." Personally after having answered a lot of questions - in a nice, helpful way, mind you - questions whose answer could simply be "RTFM", these days I just avoid them. The problem with these kinds of questions are that more and more they offer nothing to the person answering them. A lot of them are asked by people who created an account on SO just to ask that question and then throws away the key (to that account). So don't expect to get any feedback, whether karma, comments or to be marked accepted. Don't expect there to be an interesting discussion with other devs with different experiences. I mean, I was answering questions on forums long before there was any karma involved just because I like to help/teach, but for that to be interesting to me who answers questions, there must be some sort of feedback. Karma is one way but I always preferred the good ol' discussion. It means I get to learn something as well. Questions answerable with "RTFM" offer very little of that. I guess what I'm saying is that people who answers question on SO (or similar sites) are not getting paid to answers those questions. They do it for fun, learning experience, karma, status or whatever. So there has to be something in it for them as well.
  - jrumbut 10y ago
    I like your approach, just move on if it's not what you want to do. That should be the general rule, and I think that's what most people do. The other benefit is that it leaves the door open to new participants, who are excited enough to know something that they don't mind not getting the upvote. Online communication is one of the most important skills to have, and every skill takes practice.