Incorrect /sites/all documentation

@Crell - the site works either way if you're doing a single site installation. So, there is no real difference unless the user is transitioning from single site to multi-site. In that case, the user would have been best advised to put everything in /sites/sitename all along (as per the initial example).

So, the real question is simply what do we want to define as the "best" practice.

A question is whether the guidance for sites/all/modules and sites/all/themes is also appropriate guidance for sites/all/files? I'd say probably not in most cases. Can a situation be envisaged where this is a sensible configuration? Probably. Best practice and good guidance might need to focus on the main cases, at least initially.

This page is a bit confusing to a new user - I was one fairly recently. A lot of information comes down in pretty hefty chunks. I'd suggest a bit of structure on this page would make it more useful. A suggested structure is presented below. I'm suggesting a complete explanation for each of v4 and v5 (although much is the same), and a short explanation of the differences so people who know v4 can jump straight to the bit they need.

- start page -
[h1]v4.6, 4.7
1. What goes into /sites (settings, contrib & custom modules, contrib & custom themes, files)
2. When to use multiple settings files (include explanation that each site still needs to be configured using admin->modules and admin->themes)
3. Directory structure
- Include cross-reference to the Connecting Drupal part of install.txt for specific guidance on how to name the subdirectories.
4. Using the /sites directory to simplify backups

[h1]Enhancements for v5
- Role of /sites/all in multi-site configurations.
- Use of sites/all/themes, sites/all/modules.
- Guidance on placing /files (in appropriate site subdir).

[h1]v5.x
1. What goes into /sites (settings, contrib & custom modules, contrib & custom themes, files)
2. When to use multiple settings files
3. Directory structure
- Include cross-reference to the Connecting Drupal part of install.txt for specific guidance on how to name the subdirectories.
- Role of /sites/all in multi-site configurations.
- Use of sites/all/themes, sites/all/modules.
- Guidance on placing /files (in appropriate site subdir).
4. Using the /sites directory to simplify backups

[h1] Related links
Pointer to how to set up multi-sites http://drupal.org/node/43816
- end page -

I'm suggesting h1 for the main headings and an appropriate name in h2 where I show numbers above.

I'm not sure about the 'related links' bit. I just know the multi-site issue is really hard to get your head around, /sites is one piece of it. The comments below the handbook page illustrate that difficulty.

If you think it would help to structure the page along these lines I'd be happy to make a draft for review.

I just read the style guide so forget what I said about h1, h2 in the post above. At the moment I don't know how to offer better structure and stay compliant with the style guide. Breaking this into child nodes might work but I'll need to think about this quite differently.

This posting addresses /sites directory for initial single-site set-up; please QA the new documentation. The multi-site setup still needs work. This post is so long because the topic is a tangle:

Issues:

This issue: Incorrect /sites/all documentation.

Doc issue: node/53705 - /sites directory use.

Doc issue: Drupal multi-site setup documentation: request for comments

Project issue: Change default for files directory

Project issue: Use of sites/default/files as the default files directory

Handbook pages:

Use the /sites directory to keep Drupal tidy (did one small fix and moved from under 'best practices' to under 'Multi-site installation and set-up')

File and directory management (under 'best practices')

Installing Drupal (first chapter of 'Installation and configuration' book)

Multi-site installation and set-up (a grouping page with minimal content and one comment)

Database table prefix (and sharing tables across instances) (under Basic site configuration)

/sites directory setup (under Installing Drupal, just written)

One of the key problems with 'Use the /sites directory to keep Drupal tidy' is that it tries to cover both single site and multi-site setup. As stated in an earlier comment, it is also overly wordy and not well organized.

I wrote /sites directory setup to establish the basic, single-site setup, using best practices, and mentioning that other specific configuration would also work. The fact that some common files are kept in /sites/all while others are kept in /sites/default is explained. (I still think it would be better to have these two locations for common files combined! It creates confusion because it is not obvious which common items go where, and there is no strong reason for their separation.)

/sites directory setup recommends (based on what the above topics seem to say) for an initial single-site set-up of:
/sites/all/modules
/sites/all/themes
/sites/default/settings.php
/sites/www.example.com/files

Crell and pwolanin, you probably understand this a lot better than me, but from review the above, you wouldn't want /modules and /themes under both /sites/default and /sites/all though it would probably work.

1. QA /node/276, /sites directory setup
2. Re-title /node/53705 from 'Use the /sites directory to keep Drupal tidy' to '/sites directory use in multi-site installations'
3. Focus /node/53705 on multi-site set-up (as doc issue Drupal multi-site setup documentation: request for comments seems to have decided).

I removed the error from /node/53705 of placing /files under /all, and referenced '/sites directory setup' for initial configuration.

However, I'm sure it could still use more work.

vjordan: the <strong> or <b> tag can be used in place of the h1 tags you suggested, with paragraphs or ol under each.

-karldied

Crell wrote: "What I tend to do myself lately is to use sites/all for 3rd party modules (Views, CCK, other stuff out of contrib) and sites/default for modules I wrote myself specifically for a site or 3rd party modules that I had to modify for some reason."

OK, so if I understand this correctly: I can put contrib modules in /sites/all/modules or in /sites/default/modules, to the same affect: available to all sites in a multi-site setup? Same for themes? (Of course, I recognize that site-specific items can also go in /sites/www.example.com...)

Then, since /files goes in /sites/www.example.com or /sites/default, what real reason is there to use /sites/all? What goes in there that can't be put in /sites/default? (Except that it provides a convenient division for the two types of non-core modules you work with?)

OK, so if I understand this correctly: I can put contrib modules in /sites/all/modules or in /sites/default/modules, to the same affect: available to all sites in a multi-site setup? Same for themes? (Of course, I recognize that site-specific items can also go in /sites/www.example.com...)

No. Only items placed in sites/all/modules (themes, etc.) will be available to all sites.

Also, we're confusing best practices with what works. I applaud more best practices work...but there isn't consensus. My personal recommendation:
* keep ONLY modules that you really are going to use on all sites in sites/all/modules
* don't use default at all (i.e. all installs are "multi site") --- symlink default/ to your "main" site
* for each site (even if only one site...), do sites/example.com/modules, /files, /tmp, /themes

So, having said that....you can see how "multi site" is really the default nature of Drupal.

Ahh... /sites/default/modules only works for Crell because there is no /sites/example.com directory? In any case, the documentation (for initial setup) stands correctly. I'll add idea of using the symlink, and having a /tmp in each /sites/example.com Thanks.

Primarily, I removed the original error reported in this issue report: the discussion of /modules and /themes in /sites/default. I also made the language more straight forward where I made updates.

The 4.6 and 4.7 section was mostly duplicative, so I moved one best practice up to the main section, and condensed this section down to the difference from 5.x.

@vjordan: I believe also addressed all your comments. Its new placement under "Multi-site installations" 43816 a couple days ago took care of a link back to the multi-site install page.

@karldied:- good job promptly dealing with a variety of issues in this area. I was slowly making my way through the pages you referenced above and I noted a number of possible problem areas. Today I see most of those have been dealt with. Closing this thread is a good move, but I'm cross-referencing here an issue at http://drupal.org/node/110446 related to this set of updates.

Thanks for QA on my update, and opening new issue /node/110446 on an additional clarification needed.

I also meant to mention when updating this issue to 'closed' that 104340 - Drupal multi-site setup documentation: request for comments remains open and is still dealing with the whole multi-site installation matter (vhosts, etc), and there is also a comment on where /files is best placed. In this case, the new issue is probably best separate.