index and show all INSTALL*.txt README*.txt files

This is not a bad idea, but wouldn't it be better for the module to supply install/readme text in the advanced help? That way it can be translated and formatted appropriately. Then the readme/install.txt files can be shortened and point to the advanced help text.

This'll be even better once those are available online; the install.txt isn't very useful once the module is installed. readme.txt might still be useful, as will upgrade.txt which is another common one.

As for providing links on the modules page, I'm very much in favor of this but I'm not sure that our current modules page is set up to be modifiable from a module. I believe it can be themed but that's a difficult option for a module to pursue.

Our modules page is a form which means that the usual form_alter tricks apply. I bet it would not be that hard to show link to popup help there ... I tried to bring README.txt into the drupal admin UI and got shot down - #174467: Usability: Add links to README file on module and theme admin pages

Ok, after sleeping on this for awhile and really thinking about this, I understand where this is coming from and I can see the need. I am concerned that it will be actually bad for modules that have useless README files, but I can see where it will be good for modules whose README files are actually interesting.

I'm vaguely tempted to suggest that we should provide entries for all *.txt files if a README.txt exists to provide easy access to them all. It shouldn't be that hard to do, but that can come as a later patch. This one is committed.

Quick note: This brought up README files for modules that are packaged with other modules that shouldn't have them. For example, Views comes with advanced help AND a readme; this cause Views UI to show up with a readme.

A check was added to make sure the 'help' directory does not exist. If it does, it's assumed that other modules have all the control of the help and README files will not be scanned.

(using HEAD) If two modules are in the same directory with one Readme.txt and the module's folder contains no /help/ folder, the same Readme is showing for both modules.
Example: Table of contents: http://drupal.org/project/tableofcontents (same for imagecache and token)
Furthermore this readme uses html tags that are not closed in all cases. So a part of the readme is formatted as h3.

Unfortunately atm I have no idea how to improve this (besides writing global guidelines for Readme.txt and submodules structures on drupal.org ;) ).

Roi: yes, this is a problem. Unfortunately I can't think of a good way to address it, except maybe to encourage modules that have this problem to either 1) use advanced help or 2) write better README files.

I think one of the values of doing this is to raise awareness of the module and create more documentation consistency.

Like Moshe, I also wanted README files to be presented from within the Drupal UI. So anything that means that there is less repetition the better. It makes no sense to let either the README or the advanced help to fall behind the other, so I'd rather one be a reflection of the other. I don't mind which direction.
Any contributions to documentation on how to write a good README.txt would also be good.
Best Practices - examples

Here's my one-liner (from pre-advanced-help days)
Drupal Module Documentation Recommendations

/**
* Implementation of hook_help().
*/
function mymodule_help($section) {
  switch ($section) {
    case 'admin/help#mymodule':
      // Return a line-break version of the module README
      return filter_filter('process', 2, NULL, file_get_contents( dirname(__FILE__)."/README.txt") );
  }
}

IMO the best practice should be: "If you have advanced help set up, your README.txt should refer the user to the advanced help for all but basic installation instructions". Chances are, advanced help is going to be redundant with a README file anyway, so it's best to make it not automatic. Also, another reason there is that README.txt won't be readily translated.

Essentially this is a nice stopgap to make README files accessible from within the system even for modules that don't implement advanced help files. If you do, you take a few extra steps to reflect/move your README into the system. It's a touch more work but the benefits are good, I think.

Training for the search engines and LLMs

https://www.drupal.org/project/readmehelp