Issue #2115737 by darol100, rhuffstedtler, andythomnz, jemandy, ijf8090, zealfire, er.pushpinderrana, jhodgdon: Make the text in modules, themes, and profiles README.txt files more user-friendly

1 files changed, 32 insertions, 12 deletions

diff --git a/modules/README.txt b/modules/README.txt
index 477c31580c0..18845ef388f 100644
--- a/modules/README.txt
+++ b/modules/README.txt
@@ -1,18 +1,38 @@
-Place downloaded and custom modules that extend your site functionality beyond
-Drupal core in this directory to ensure clean separation from core modules and
-to facilitate safe, self-contained code updates. Contributed modules from the
-Drupal community may be downloaded at https://www.drupal.org/project/modules.
+Modules extend your site functionality beyond Drupal core.
 
-It is safe to organize modules into subdirectories, such as "contrib" for
+WHAT TO PLACE IN THIS DIRECTORY?
+--------------------------------
+
+Placing downloaded and custom modules in this directory separates downloaded and
+custom modules from Drupal core's modules. This allows Drupal core to be updated
+without overwriting these files.
+
+DOWNLOAD ADDITIONAL MODULES
+---------------------------
+
+Contributed modules from the Drupal community may be downloaded at
+https://www.drupal.org/project/project_module.
+
+ORGANIZING MODULES IN THIS DIRECTORY
+------------------------------------
+
+You may create subdirectories in this directory, to organize your added modules,
+without breaking the site. Some common subdirectories include "contrib" for
 contributed modules, and "custom" for custom modules. Note that if you move a
 module to a subdirectory after it has been enabled, you may need to clear the
-Drupal cache so that it can be found.
+Drupal cache so it can be found.
+
+MULTISITE CONFIGURATION
+-----------------------
+
+In multisite configurations, modules found in this directory are available to
+all sites. You may also put modules in the sites/all/modules directory, and the
+versions in sites/all/modules will take precedence over versions of the same
+module that are here. Alternatively, the sites/your_site_name/modules directory
+pattern may be used to restrict modules to a specific site instance.
 
-In multisite configuration, modules found in this directory are available to
-all sites. In addition to this directory, shared common modules may also be kept
-in the sites/all/modules directory and will take precedence over modules in this
-directory. Alternatively, the sites/your_site_name/modules directory pattern may
-be used to restrict modules to a specific site instance.
+MORE INFORMATION
+----------------
 
-Refer to the "Developing for Drupal" section of the README.txt in the Drupal
+Refer to the “Developing for Drupal” section of the README.txt in the Drupal
 root directory for further information on extending Drupal with custom modules.