Skip to content
 

Why it doesn’t make sense to chew people out for not reading the help page

Karl Broman writes:

Barry Rowlingson gave an interesting talk at UseR 2011, “Why R-help must die!” He suggested the Q-and-A type sites Stack Overflow (on programming) and Cross Validated (on statistics), both part of Stack Exchange.

I haven’t used R-help recently but I do occasionally send people there. Just to see what was going on there, I clicked on over, did a little searching, and found this delight from a renowned professor of R. There’s something about the “please” there that just makes it all that much more special. (In contrast, the advice here to “please do your homework” just seems rude.

I have a larger (or maybe smaller) point to make, though, which is about the silliness of advice to “read the damn manual” etc.

Several years ago I read a fascinating book called City by William Whyte. He and his students had gone around various public places in NYC and observed how people actually behaved—how they walked, sit, stood, and interacted.

One of Whyte’s central themes was that it does not make sense to design things as you want them to be used; rather, you have to design them so they work well as they actually are used. One of his examples was where people stand on the sidewalk. Whyte and his students noticed that people would often stop for brief conversations at the busiest spot on the sidewalk, a few feet from the corner at an intersection. The inclination of many planners would be to somehow make it difficult to stop and stand there, maybe put bumps in the sidewalk or have some annoying beeping or a sign telling people to move along. Whyte suggested that, instead, city planners should increase the area of the sidewalk at these popular spaces, for example by having them take over some of the street at the corner. Then you allow people to walk on by, in the context of existing patterns of where people like to stand.

Now let’s return to the topic above. The sad truth is, very few people read the help page. The help page is boring. Most of us would rather read People magazine, or the New York Times, or even Gawker. To chew people out for not reading the documentation is to fight the tide.

P.S. Just to be clear: I think the renowned professor is doing a useful service to the community in responding to the R-help list. And, given that he’s doing it for free, he should feel free to answer in whatever tone he’d like. I am not objecting to his tone, merely expressing my amusement. My main point in this post is to point out the fighting-the-tide nature of typical “read the manual”-style advice.

39 Comments

  1. Trey says:

    I would further add that the R help files seem written for people who already know what they’re doing, which is quite paradoxical if you think about it. Most users don’t learn R as they do regular programming languages; they learn how to use R to conduct analyses and maybe later start to get interested in the programming side of it. Instead, I send my students to the UCLA Stat Computing site for help.

  2. Karl Broman says:

    I once had a response on R-help that was something like, “Do read the documentation. In particular, see [deep within an obscure document].” The renowned professor of R can be unnecessarily insulting, but he does answer the question, and I kind of like to be pointed to the relevant documentation. So in response to questions about my own software, I try to answer the question and also indicate which documentation to read.

  3. Nick Cox says:

    I don’t know. I would much rather read R documentation than People magazine, whatever that is, but people must speak for themselves.

    Also, we’ve been here before.

    1. Absent people whose job it is to provide technical support, R clearly does depend on (a) people reading the documentation or (b) people with better things to do helping those who lack the time, inclination or ability to do so. Whether this will kill R very slowly over the long term strikes me as an interesting question. For now, it is clearly doing pretty well.

    2. This recent sample from R help is terse, but it contains specific technical advice and is not ruder than a sizeable fraction of blog comments (often from people hiding behind anonymous or cryptic identifiers). Perhaps you wouldn’t want Brian Ripley as a dinner guest, but he’s helped thousands of people directly or indirectly.

    3. Those who want a kindler, gentler tone on help lists are always welcome to contribute to those lists and provide such examples themselves. Many if not all people who follow those lists closely come to value a style that may be short on diplomacy or discursive chat but is high on content. What is futile is to object to tone on mailing lists and do nothing about it!

    • Andrew says:

      Nick:

      I agree. As I believe I’ve written elsewhere, I think the renowned professor is doing a useful service to the community in responding to the help list. And, given that he’s doing it for free, he should feel free to answer in whatever tone he’d like. I am not objecting to his tone, merely expressing my amusement.

  4. C Ryan King says:

    Just helpfully answering all comers to all lists sets you up for an unmanageable flood of requests. Lots of people would rather someone knowledgeable show them how / do the task, but that’s very expensive. R wants to subsidize help with the things that are really R’s problem, not teach what $stat_method is and how it works. BDR could have answered his question, but he also already wrote a book to do that (MASS section 12.1). You also seem to answer plenty of questions with “see BDA section 8.4.12”.

    I read and sometimes answer the R-sig-mixed-models list, and perhaps 1/4 are questions about how the relevant R packages work and 3/4 are about how to use or interpret mixed models. That’s fun to talk about, but I’d like to separate that from questions about the software itself.

    • Murray Jorgensen says:

      I disagree. I don’t believe that it is practical to separate the software and the conceptual problems in the area of mixed models. And if you could there would probably be a big demand on the developers to facilitate the fitting of nonsensical models!

  5. Rick Wicklin says:

    Help pages are great when you know where to go to look for what you want. However, a new user of software (or an infrequent user) is often faced with the challenge of not knowing where to begin. For this purpose, discussion forums are more useful, and the more experienced users can provide links to the documentation (civilly, of course!) when the question involves simple syntax or an optional argument.

    Yes, it is tempting to respond “Type your question into Google and hit ENTER; Click on the first link that appears,” or “Do your own homework!” However, the easier response is just to not answer those postings. Perhaps they will be answered by someone who was recently a novice himself, and thus produce a new generation of mentors.

  6. Raymond says:

    Stata help is so much better than R’s “?commandname”. Stata help even offers several examples on the bottom using the system dataset.

    • C Ryan King says:

      Stata help is great, and takes up a whole bookshelf. That kind of documentation costs money.

      • Jeremy Miles says:

        Agreed, and I think the problem in R is made worse, becuase it’s fun to write functions and packages, it’s not fun to write help files.

    • Sam says:

      For pay software you really need to compare apples to apples, and Stata’s help pales in comparison to SAS. R’s help files are a little bit worse than Stata’s, but only because free software is rarely well documented. SAS’s help files could be the textbook for a stats course

      • Nick Cox says:

        Apart from Sam’s judgement here, which stands as Sam’s view, and which I don’t endorse, there is a blurring of categories here which might confuse those not familiar with Stata.

        Stata’s help files are often terse, but behind the help files are manual entries, often lengthy. As from Stata 11, the manual entries are .pdf documents directly linked to the help.

  7. DavidC says:

    Yep. It’s all about search, not manual pages.

    I think it’s relevant to note that Joel & Jeff often talk about how the primary value they’re trying to generate with Stack Overflow isn’t for the question-askers — it’s for the people who can, after the question has been asked and answered, easily and quickly find their answer via search engines.

  8. eric says:

    This seems apropos of the National Field story just below, as I’ve heard numerous reviews of National Field and it’s distinct lack of usability for people working in “field”.

  9. Jonathan says:

    I’m with Raymond. The analogy to Whyte is to followup and figure out WHY people aren’t reading the manual and make it useful to them. Stata manages to make the manual interesting and useful. What exactly is the difference between: “Don’t bother to read the manual” and “Don’t bother to know what you’re doing.” A lot of documentation is terrible, but I find even terrible documentation somewhat useful.

    There is another added benefit. Until you read the manual, you can’t possibly know everything you can do, other than the truly boring task of systematically going through the menus. Maybe it’s just me, but even bad documentation is more interesting than that…

  10. Sebastian says:

    I have two, slightly diverging comments on that:
    First, R-help is intimidating and notorious for its rough tone. I go out of my way to avoid asking questions there.

    Second, I don’t think what Brian is doing at the exchange you link to is so bad – he actually is providing specific and – as far as I can tell – useful advice and only then tells the user that there would have been a better place to ask the question.
    It seems reasonable to me that in order to maintain free and volunteer-driven support system, you need to encourage some degree of order.

  11. Kaiser says:

    Wow we posted on Cross Validated on the same day.

    I used to look at R-help, and actually loved Ripley’s responses. He’s acting as the moderator of an unmoderated forum. Also, if you’d judge him based on the totality of his responses, you’ll find that good quesions are rewarded with good answers. Even in the link shown, he provided an answer; in other cases, I have seen him being even more curt! His replies are legendary on that list.

    I am glad to learn about the Whyte book, sounds very interesting, and is a totally appropriate analogy for this situation. Stack Overflow is great but I have my doubts about Cross Validated, as I discussed here.

    Like others, I also think there is a difference between technical support and user community. I see R-help as more technical support and Stack Overflow as the latter.

    • kjetil b halvorsen says:

      Brian Ripley is amazing, and when he first answers he does it thoroughfully and to the point, with technical references. Sometimes I got private email from him (CRAN is used to check out consequences of changhes to R, and it seems BDR often is doing those
      full-CRAN checks. I ahve a few unimportant packages on CRAN, and when he discovered errors in them he write. He then goes for it completely, once I got an reply mail correcting (with references) some error I had made in referring to old English!

  12. @Rick Wicklin: I think you hit the nail on the head– it’s hard to know where to look if you’re a newbie. One problem is only having learned one way of talking about something — experts have ranges of synonyms for things and experience in how different explanations fit together, which helps immensely in searching for precise answers and then understanding them.

    I love being able to answer questions to our mailing list with “look here in the doc and get back to us if it’s still unclear”.

    @Jonathan: There is a pretty broad line between “don’t bother to read the manual” and “don’t bother to know what you’re doing”. The problem with large software packages like R is that the doc stack is hundreds of pages long and still incomplete. You can keep searching, but have no idea if you’ve exhausted the options in the doc.

    The asker should be willing to do a bit of work. There’s not much more annoying than being asked to do someone’s homework for them. Often, I have to point people to a FAQ on how to ask for help (this one by our friends at Boost Spirit, the parser we’re using for Stan, which is notoriously difficult to understand due to its reliance on binding for laziness in a heavily templated C++). Here’s a similar FAQ on how to ask for help (this time from Mozilla).

  13. Elissa says:

    The Stack Exchange sites are far more friendly, not to mention easier to navigate and search. I think the way communication is dealt there makes the question-askers a lot less intimidated and the question-answerers a lot less mean. It’s a win all-around. My experiences on SE sites always result in great learning experiences for everyone, while lists such as R-Help end with an insincere “HTH” and me feeling like “thanks…kinda…”

  14. R help pages need their own R help help pages. After much struggle, it’s possible to eventually intuit the structures and conventions, but it is difficult even for the conscientious to know what to make of much of what R help offers. I feel like the student who goes to the Zen sensei:

    Please explain recursion, Ryushin Sensei.

    To understand recursion, you must first understand recursion.

    • kjetil b halvorsen says:

      I dont think this is correct! R help, for instance, is much better than everything offered by microsoft.! I don’t
      have to use Excel anymore, thank God, Excel help pages are terrifying! they only include very trivial examples, and if your problem is not that trivial, you are lost, completely. I once worked a place with an microsoft service contract, and I did a call, some EXCEL MACRO did not do what the help page said. I was first answered from Oslo, but they said this kind of questions could only be answered from Stockholm, so I was directed there. I talked for a complete half hour with an extremely rude swede, who had nothing to say, but that my problem DID NOT EXIST. Then, after half an hour, he finally understood, it was a known&documented error, and he could fax the relevant page.

  15. efrique says:

    I’m actually in favour of telling people to read the help (or much better, *showing them where in the help their question is answered* – mainly because many don’t think of it but would be happy to look there. But it must also be done with understanding, because some of them have looked but haven’t found the right help or have found the right bit of help but still don’t get it. I know that happened to me a few times early on – I had read exactly the bit I should have but I didn’t understand everything I was supposed to glean from it.

  16. Xi'an says:

    Uh?! The first day at class (R class), I force my students to read R-help pages to start programming. Within the hour, they are already familiar with it and indeed start programming. I never noticed them to be rude but, of course, I am French so I would not notice!!!

  17. Yihui says:

    I believe many people must have been mad if they had stayed in a mailing list answering questions for more than 12 years (especially some are already documented in the help pages)…

    But on the other hand, I also feel the mailing list is becoming very old-fashioned, and Stack Exchange has provided a far better way for communication and learning.

  18. Neuroskeptic says:

    Surely the analogy with Whyte can be extended to the manuals themselves, though. They’re meant to be read – but few people do – we need to work out why.

    I think the problem is that most people only want to read a manual when they get stuck. A manual is never going to be read cover-to-cover; or at least, the people who do read them cover-to-cover, are not the ones we need to worry about because they’ll know everything by the end.

    Making manuals easier to use for someone who just wants to find out how to do X, is the important thing.

    • kjetil b halvorsen says:

      Adding to my former reply. R help pages could do with a few more trivial examples, often all the examples are very advanced ones!

  19. John says:

    Sorry, but I just don’t get all the hand wringing over this. The problem is that people are often lazy and self-centered. It is one thing to call a commercial help line and pay someone to “do your homework for you.” It is quite another to expect people on the web to solve your problem for you gratis because you are too lazy to do some basic homework. I am old enough to remember the old USENET news groups and the acronyms RTFM and STFW, which were born out of frustration with lazy people. Prof. Ripley’s gentle reminder was quite kind compared to those reminders… Eric Raymond (“ESR”) put together an essay entitled “How to ask questions the smart way” (http://catb.org/~esr/faqs/smart-questions.html) which should be required reading. I would note that I try to do this when I am stumped and have been quite pleased by the responses I have received from many Open Source communities.

    • Andrew says:

      John:

      My point is not that it’s immoral for someone to answer help questions with generic “Read the manual” responses bur rather that it’s pointless. See my discussion of Whyte’s book in the above post. If you want to be helpful to people, it’s helpful to understand what people do.

      • John says:

        Agreed that we should be helpful where we can. I often answer such questions in areas where I can help, even when it is obvious a bit of searching would have let them find it themselves.

        I disagree that gentle reminders are pointless. Some people learn from them and we do get what we accept. My own “gentle reminder” is something like “Google Advanced Search is our friend…” and then answer the question and supply links for further help. Many people will not take the time to do this and just ignore the question. Everybody benefits when people follow ESR’s advice and “ask questions the smart way.”

        • eRic says:

          I have to second this point. Some people do learn from them. Other people, who did not learn from them will appear and clog up the sidewalk. Unknown to us, some people will read the “Read the Fine Manual” responses to previous messages and learn not to clog up the sidewalk prior their first walk down r-help lane. Also unseen by us are the people who formulate the question in a way that can be answered by the list only to realize that they now have enough understanding of the problem that they don’t even need to send the list the query any more–they have answered their own question.

          It is not rude to point out that other people are being rude. R did that when the original poster asked the list to do the homework part of his/her homework. A change of venue would not change the nature of the query or the appropriateness of the response. It might be funny when people are confronted with their own rudeness, but it it seems like that is not the source of your amusement.

  20. K? O'Rourke says:

    Andrew:

    With the professor in question it may have become more of a reflex like saying “bless you” when someone sneezes?

    For “helpful to understand what people do” Stephen Wolfram has a recent only line video to demonstrate how a given
    a bunch of words like “polar plot f(x)” the right syntax is generate and then “add a purple frame” and it rewrites the
    syntax with appropriate options coded for you. (Other bunches of words might not work well – but seems a start).

  21. The problem is that R’s documentation (which is usually for functions) often includes references to other unfamilar functions and datasets. For example, ‘table’ references ‘cut’ and the ‘airquality,’ ‘warpbreaks,’ and ‘state’ datasets. There’s no context in the help file as to what the datasets are, or what the other functions are.

    As annoyed as I get about SAS’s class of middleschoolers, there’s something to be said for being familiar with the datasets used for examples.

  22. Matt says:

    How do we know that issuing RTFM’s is like ‘fighting the tide’? Or, that most R users don’t read the manual? Your last second-to-last paragraph sounds a little like story time.

  23. You might be interested in my working approach to moral accounting “The Neurotic Manifesto” on my blog.

    Because on the one hand I agree it doesn’t make sense to chew out people for not reading the help page. Extending that logic, I intuit it doesn’t make sense to chew people out for chewing people out for not reading the help page. On the other hand, policing does move the animal spirits. Of course, policing against policing also moves the animal spirits. I still think coordinating (including policing) to improve our collective welfare is a good idea, or at least the best of all possible doomed projects to engage in. But I think we should be sensitive to how inchoate it is at the level of first principles, at least as we can discern them.

  24. eRic says:

    Thinking about this some more… Starting with Whyte and his observations is, in my opinion, an error. R-help is not trying to build a roadway. R-help is trying to build a community. Successful communities have to communicate and instill the norms and mores of that community to the young and reinforce them when they are violated. There can be conflicting norms. When there is a perception that a norm is violated, it takes judgement about how to formulate a response. No free-riding is one norm on r-help. Formulating questions that do not waste everyone’s time is another. Civilized responses, even when other norms are being clearly violated is another norm. For such a community to last all of them need to be sustained.

    Eric