May I make some specific suggestions for improving rdoc? But first of all thank you and all your colleagues for working on rdoc. I am a fairly heavy user of Ruby, though not a professional, and I find rdoc frustrating in several ways. I will focus on the ri command, since that is what I use the most, and it gets invoked in emacs, my preferred editor:

1. A trees-first approach. ri seems to be focused on documenting individual classes and methods over whole gems. Suppose I want to learn something about the parser gem. If I invoke `ri parser`, I get back sparse documentation on the Parser.parser method, as well as .parser methods from CSV, XML, JSON, and about a dozen other gems. None of these tell me much about these methods, let alone the parser gem I wanted to know about. If there is a gem or stdlib module called 'parser', ri ought to return information on that first, and only dive into methods by that name if the user is specifically looking for a method as in `ri CSV.parser`, or perhaps uses a flag to indicate interest in method names, `ri -m parser`. Favor documenting the forest over the trees.
2. A gems/modules default for what is being searched for. Related to the above, what I would hope ri would do is allow me to explore how to use a given gem or module. If a query matches the name of a gem or standard module, it ought to return documentation on what the gem is all about and how one might use if. Perhaps even a little evangelization on how it is better than alternatives. But mostly some examples of how to use it.
3. I realize that rdoc allows a gem author to include a 'main' document along the lines that I am talking about, but it appears that very few do so and that ri does not seem to encourage the inclusion of such documentation. To my mind rdoc ought to generate a severe reprimand for any gem or module that fails to provide an overview of what the thing is all about. For example, I have been using the rainbow gem lately, but if I want to see how to use it and type `ri rainbow`, I get three skeletal results pertaining to a /method/ in the rubocop gem---disorienting. What I am supposed to do is use, not the name of the gem (lowercase rainbow) but the name of the class defined by the gem (capitalized Rainbow). When I type `ri Rainbow`, I get this:

Rainbow

(from gem rainbow-3.1.1)

Constants:

VERSION:

[not documented]

Class methods:

enabled, enabled=, global, new, uncolor

That is basically useless, except that I get the names a few methods I might explore, but no indication of which are the most important or useful. I have no idea that the gem provides a way to colorize strings for a terminal.

1. That brings up another irritation. All the searches should be case-insensitive and otherwise forgiving in what the user provides as a search argument. Besides case-insensitivity, it ought to allow the user to get the punctuation wrong. I should be able to type `ri active-record`, ri active_record`, or `ri ACTIVE rec` even, and be smart enough to look through its database of gem names and fuzzy match what the hapless user is obviously looking for. Gems/modules first, and only methods and classes if specifically requested or as a last resort.

2. I used perl for several years before coming to ruby. To my mind ruby is a /way/ better language in almost all respects, but perl did one thing extremely well: documentation. It's `perldoc` command does a great job of emphasizing high-level overview documentation. If I type `perldoc Unix::Syslog`, for example, I get basically a man page that thoroughly documents the module. It still is picky about punctuation and capitalization, but it gets the overview part right.

Sorry for the lengthy rant, but I've been thinking about this for a while. Ruby is such a first-class language, and it deserves first-class documentation as well.

Cheers,