INSTALL.txt should explain about where to put new modules/themes

That is a good idea.

This looks pretty good, and I like it...

A few minor comments:

a)

+Drupal has a community that contributes lots of both "themes" and "modules",
+a module is a plugin that adds functionallity to Drupal while a theme changes
+the frontend look and behaviour of your site.

This should be two sentences. As it is, it's a "comma splice". Your other choice would be to change the comma into a semicolon (;), but it's never correct to join two complete English sentences with a comma.

Also, in Drupal we normally adopt American spellings, so it should be behavior rather than behaviour.

b)

+Modules:
+  sites/all/modules/custom module
+
+Themes
+  sites/all/themes/custom theme

I don't like having spaces in the directory names.

c)

+If you run a multisite installation you will want to do this a bit differently,
+you can read more about that on the multisite part of this file.

Again, this should be two sentences (see a above).

So... I took a closer look at how this new section would integrate with the rest of INSTALL.txt.

It comes right after a line that says to go to d.o to download modules and themes, and right before a section on customizing the theme that is actually mostly about downloading a new theme, and which has a link to http://drupal.org/handbook/customization, which is actually the Site Builders Guide.

It seems like all of this should be incorporated into the new section instead, and maybe the new section should be called "Building and Customizing your Site" or something like that?

nenne: Your patch doesn't apply for me in Drupal 7 HEAD.

Also, the text you added needs some proofreading... If you make a patch I can apply, I will edit it.

I am proof-reading this, will add a new patch shortly.

Here is a slightly edited version of the patch above. I'm happy with this version, of course...

EDIT (added): Sorry about the file name on the patch. It does pertain to this issue (569042) and not what the file name implies. Whoops!

Not to bikeshed this too horribly, but as long as we're going here, I think it's a good idea to also talk about separating custom modules/themes from contrib modules/themes.

I've seen this done in the following ways:

sites/all/modules/contrib
sites/all/modules/custom

or:

sites/all/modules/contrib_module_1
sites/all/modules/contrib_module_2
sites/all/modules/contrib_module_3
sites/all/modules/custom/custom_module_1
sites/all/modules/custom/custom_module_2
sites/all/modules/custom/custom_module_3

This might be overkill. But at the very least, I think we should not use "custom_theme"/"custom_module" as the example here, since you almost never actually want your custom stuff under the root sites/all/modules directory, in my experience.

@webchick
Yep, I do that myself, but it's a Drupal-developer convention, not a Drupal-webmaster one, and probably overkill for the small-to-medium site builds, especially first-timers.
A link to some doc that explains why this can be helpful could be ok, but this is probably too advanced a choice to document in the INSTALL.

Besides, only option #2 is compatible with drush :-( . That spoilt my whole architecture.

There are a few architectural choices here, so best to recommend one basic way and take advanced options to discussion in the handbook. I think.

Fair enough. Then a simple enough patch is just to replace "custom_module" with "example_module" or something. I just really don't want us advocating bad practices off the bat.

Sounds reasonable to me: here's custom_module -> example_module

As this is exactly the same as the last (RTBC) patch except the small change advocated by webchick in #20, I've taken the liberty of marking it RTBC again (assuming test bot agrees, which it should on a .txt file patch, unless I've screwed up the patch or something).

Committed to CVS HEAD. Thanks.