add a README.txt file in both /modules and /themes

+1
Can't hurt.
Perhaps a reference to a 'best practices handbook page explaining the dir structure

... if there was such a thing! I can't find it!

( looked under Coding Standards Setting up a development environment Module developers guide ... The best mention I found was Creating modules - tutorials » Creating modules - a tutorial: Drupal 5.x » 01. Getting started.

+1 as well.

The attached file changes "modules" to "themes" to match the file.

I think this counts as a bug. If there's documentation on sites/* to link to that'd be good too.

http://drupal.org/node/176043 is definitely the page to link to.

Yes, but it makes no mention of the /sites/{sitename}/[modules|themes]/ option - which is also useful.

Something like:

Contributed modules and themes can also be placed in the directories /sites/{sitename}/modules/ and /sites/{sitename}/themes/. {sitename} will often be 'default'

Contributions placed there will only be available to the named site, whereas those under /all/* are available globally. For a single site setup, this probably won't make much difference to you but if you ever start modifying downloaded code for your own use, it's a good idea to isolate your changes from the clean versions. It's possible to have two versions of any module (even core ones) available on the site. Your installation will choose from the most specific one available (first /sites/sitename/modules, then /sites/all/modules then /modules). You can take advantage of this to test patches without damaging your existing files.

Also, you can place modules anywhere within subfolders underneath any of these /modules/ folders. They will be searched recursively when you visit your admin/build/modules page. You can use this to further organise your available items.

... Hm ... OK, maybe that's a bit heavy for 'getting started'. :-). But we do need the full picture in a handbook somewhere

that's true - but if we link to that page (ideally with a path alias) we can open a docs issue to add the additional information. It's definitely the right page though.

I think it would be nice if all the .txt in the root install were moved into a ReadMe directory and a lone "Read Me first.txt" briefly explaining which directories are off limits. With all the files scattered all over, I think there would be less chance of others reading any of them. Have one stand out and have clear and concise information there.

Yeah, but I gotta disagree.
That one true readme would be too big and seldom get read.
A 1KB README you see by accident when just about to start adding stuff is much more serendipitous, and leads to a gradual learning process.
Heck, name it DONT_PUT_ANYTHING_HERE.txt :-)

>> DONT_PUT_ANYTHING_HERE.txt

I'm sure there's a reason we don't do stuff like that, but someone want to tell me why not?

So are we expanding/changing the scope of this issue? If so, the title needs to be updated appropriately.

If not, can we get this change RTBC and create a new issue for the additional work and/or modifications?

As a newbie - the proposed XXXX_readme.txt are very clear and proposed locations are fine. I like having the "http://drupal.org/node/176043" link in the readme.txt file.

If you start having DONT_PUT_ANYTHING_HERE.txt files - you would need to put them in alot of places. So I don't like that idea...

Yeah. Named text files are tacky, I didn't think it was a great suggestion. forget it.
But +1 on just getting these two normal READMEs in.

It would be nice to get an alias created. I'm not sure how that gets accomplished. Maybe a request in the documentation queue?

If getting the alias created is going to take too long, we should mark this RTBC so it can get included for the next RC. (Not sure how long before that happens.)

I think you have to be a "site maintainer" to create aliases. Afaik this means a 'task' in the Drupal.org webmasters queue should work.

That's two votes to get this in (and update later for the alias). RTBC.

Hm, this does not look like multisite friendly, suggesting sites/all to everyone. IMHO that text needs to be expanded on a little bit to cover the non-multisite (sites/all) and the multisite case as well.

Updated to include a note for multisite installations. I tried to keep it short. We do provide a link to the updated documentation for more details.

Whoops, set for review.

I'm not sure if new files are easier to introduce via patch - in case they are, here is one to add both, as they are from #23 above.

(cvs add will of course still be required before these new files can be committed)

Committed this one, thanks.

I'm sorry, but can I suggest a small follow-up patch?

In the original, there are lines like:

+under /sites/{sitename}/modules/, where sitename is the name of your site

I know what this means, but since it references "{sitename}" and "sitename", some might think that your directory should be formed as:

/sites/{example.com}/modules

The attached patch changes the second "sitename" to "{sitename}" so that they match.

Committed, thanks.