[documentation] [Documentation bug] Incorrect sites/all documentation

[vjordan]

Issue status update for 
http://drupal.org/node/103915
Post a follow up: 
http://drupal.org/project/comments/add/103915

 Project:      Documentation
 Version:      <none>
 Component:    Admin Guide
 Category:     bug reports
 Priority:     normal
 Assigned to:  Anonymous
 Reported by:  Crell
 Updated by:   vjordan
 Status:       active

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  [1] 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  [2] 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.


[1] http://drupal.org/node/260
[2] http://drupal.org/node/260




vjordan



Previous comments:
------------------------------------------------------------------------

Mon, 18 Dec 2006 03:35:09 +0000 : Crell

The example of the "new 5.0" sites/all support on this page [3] is
wrong.  It says:



/drupal
  /sites
    /default
       settings.php
    /all
       /modules
       /themes
       /files

Which is not correct.  sites/all does NOT provide any magic support for
files, and in fact putting files there is a rather bad idea.  It's for
modules and themes that you want shared only.  A more correct example
would be:



/drupal
  /sites
    /default
       /files
       /modules
       /themes
       settings.php
    /all
       /modules
       /themes

(I'm not sure what the rule is for what counts as "critical" for
documentation, but I figure "incorrect information" is a good guess. 
Please correct if I'm mistaken.)
[3] http://drupal.org/node/53705




------------------------------------------------------------------------

Mon, 18 Dec 2006 03:42:44 +0000 : Crell

It's not just the example, I just realized, but the descriptive text as
well.




------------------------------------------------------------------------

Mon, 18 Dec 2006 12:52:00 +0000 : pwolanin

@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.




------------------------------------------------------------------------

Mon, 18 Dec 2006 16:07:53 +0000 : Crell

Best practice is to keep site-specific files with site-specific code,
not to confuse it with site-generic code.  Yes it will not-break if you
put your files directory in sites/all/files, but it technically doesn't
break if you put it in themes/engines/files either.  That doesn't make
it a good idea. :-)  Encouraging people to keep site-specific everything
together from the get-go is a good thing.