Removed the section about ri, added --no-ri and --no-rdoc flags.

[chancancode]

1. I don't know anyone who actually uses ri & rdoc in real life :)
2. generating ri & rdoc usually takes more time than installing the gems themselves
3. ri is sloooooowwwww
4. For beginners, the ri "UI" and the query interface is confusing
5. Google / ruby-doc.org is much faster/easier to read
6. Running rvm docs generate during class is a waste of time

I don't think anyone is going to miss them :P

[tjgrathwell]

I agree with all this. The only issues are:

1. Now the 'Tools' page looks a little anemic. It probably should be prettied up a bit and more focused on how to get answers from the internet ('do a search on ruby-doc' is a good start but doesn't help with Rails classes). But that can probably be answered in a future commit.
2. People now have to type --no-ri --no-rdoc all the time. I imagine adding a step for people to add that to their .gemrc might cause more problems than it solves.

[nuclearsandwich]

@alexch had a reason to keep ri. Also I've started using it again now that I do a lot of hacking on airplanes. I'd like him to weigh in before we nix ri. I was for it once, I can be for it again but ri is a pretty underrated tool these days.

[alexch]

ri is awesome and the only reason people don't use it is because
everybody's blog entry adds --no-ri to their install instructions. We can
break the cycle of madness!

A few times I've taken a stab at patching rubygems to build docs in the
background when available, but I haven't quite made it work yet.

[alexch]

For beginners, the ri "UI" and the query interface is confusing

What's confusing about "ri String" or "ri String.reverse" ?

[chancancode]

1. Querying: [I always thought you have to use String#reverse... but apparently that's not true]
2. Querying: ! ? [ ] << ... might not be safe in certain shells (?)
3. Querying: It doesn't work for language constructs like for, if, while, etc, and ruby-docs sort of does that
4. UI: it uses less (?) by default, so the first question would be, "How do I get out?"
5. UI: the HTML docs are much more "friendly" and "familiar" than the terminal thing. It's easier to read/search/jump/etc.

I don't mean to bash "ri/rdoc", it's just that I've been skipping this section when I teach because I don't use it, and a few other teachers told me the same thing so I thought I'd submit a PR.

I think it's more beneficial if we teach them to search for stuff online, and we should probably write that section regardless. At the minimum though, the doc gen should be moved to install fest rather than in the class notes.

[alexch]

1. Querying: [I always thought you have to use String#reverse... but
   apparently that's not true]

Foo.bar finds both class methods and instance methods. (Foo::bar or Foo#bar
are exclusive and I never use them.)

1. Querying: ! ? [ ] << ... might not be safe in certain shells (?)

Correct, but noobs will have to learn that sooner or later, and it's
correctable with single-quotes.

1. Querying: It doesn't work for language constructs like for, if, while,
   etc, and ruby-docs sort of does that

It does?

1. UI: it uses less (?) by default, so the first question would be, "How
   do I get out?"

Fair enough, but I think by default just hitting space works, right? Maybe
that's just how I've configured my LESS environment var.

1. UI: the HTML docs are much more "friendly" and "familiar" than the
   terminal thing. It's easier to read/search/jump/etc.

True -- and I definitely recommend teaching them -- but command-line typing
takes much less time.

I think it's more beneficial if we teach them to search for stuff online,
and we should probably write that section regardless.

Oh, there is no such section? There definitely should be.

At the minimum though, the doc gen should be moved to install fest rather

than in the class notes.

Moved or copied, sure.

[likethesky]

I have to say, in my beginner class on Saturday the queries didn't work (so I guess I'm still a shell 'noob' of some sort!), and I just showed them how to google and get a much better, much prettier, more informative version of what ri provides anyway.

I agree that for planes and other disconnected places, it's nice, but those are getting farther and fewer between and mostly I need to do too much other googling when coding anyway, that the little snippets I could get done otherwise, by using ri are not usually worth even starting to code when disconnected.

And if I do any amount coding anyway, I want to git push somewhere safe ! Yeah, I suppose the USB key on my keyring would do... Anyway, my $0.04 worth.

I vote to ditch it, even though it might be useful to a small percentage of them, some of the time...

[alexch]

I know I can't convince you that "ri Process.fork" is one gesture and
switching to a browser, googling, scanning the hits, clicking,
scrolling, etc. etc. is many many gestures and not only takes more
time but is more likely to break flow. But perhaps someday you will
come to realize it on your own. :-)

[kattrali]

I use ri! :)
I can definitely agree that gem installation takes a long time when not using --no-ri, but in the few cases when I don't have Internet access, like when conference wifi gets spotty during a workshop (or like the last five days, courtesy of storms in the Midwest), it is so incredibly handy.

As a side note, one other alternative not mentioned is DuckDuckGo.com's !ruby [query] syntax. It is a really easy shortcut to ruby-doc.org/, and almost as fast as command-line lookup when DuckDuckGo is the default search engine.

[nuclearsandwich]

DuckDuckGo is my full time search engine, in fact I'm the one who originally suggested putting !ruby, !rubydoc, and !rubygems in the command library. The amusing thing about the bang commands on ddg is that they're useful specifically because they're a return to the say-what-you-want command-line ethos.

[kattrali]

Aha! Thank you sir, !ruby is excellent. :)

[alexch]

I always said, Google is the command line for the Web. They've dumbed it down a bit lately but I'm glad DDG is picking up the slack.

On Jul 3, 2012, at 5:09 PM, Steven! Ragnarökreply@reply.github.com wrote:

DuckDuckGo is my full time search engine, in fact I'm the one who originally suggested putting !ruby, !rubydoc, and !rubygems in the command library. The amusing thing about the bang commands on ddg is that they're useful specifically because they're a return to the say-what-you-want command-line ethos.

---

Reply to this email directly or view it on GitHub:
#75 (comment)

[nuclearsandwich]

Hilariously, this thread has increased my ri usage about 400% and I now have Vim and Alfred bindings to ri.

I think at this point I'd like to keep ri in the curriculum but it's currently in a strange place (as with all of our Ruby non Rails work). With the mailing list discussions of deep curricula extensions I think an in-depth intro to Ruby would be an excellent place to talk about ri, rdoc, and gem server as Google alternatives for quick documentation checking and research.

That would solve the problem of discussing ri and then basically telling people to forget about it while leaving it in the curriculum in a place where it is most likely to be useful to students and volunteers alike.

[alexch]

just submitted rubygems/rubygems#352 -- go give it some +1 love (unless that's gauche -- I'm never sure) and maybe this debate will be moot soon

[intuedge]

Since the @alexch rubygems change to build the docs in the background has already been merged, it seems like this PR has been obviated, but the comments about having better docs for the installfest and curriculum for pointing users toward self-help are still relevant. How do we get there from here?

[nuclearsandwich]

@intuedge, I've created #83 to address the action items that were discussed in this issue. We can continue the discussion there.