Issue #2115737 by darol100, rhuffstedtler, andythomnz, jemandy, ijf80…

…90, zealfire, er.pushpinderrana, jhodgdon: Make the text in modules, themes, and profiles README.txt files more user-friendly

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.

profiles/README.txt

@@ -1,18 +1,28 @@
-Place downloaded and custom installation profiles in this directory to ensure
-separation from Drupal core profiles and to facilitate safe, self-contained code
-updates.
-
-In multisite configuration, installation profiles found in this directory are
-available to all sites during their initial site installation. Shared common
-profiles may also be kept in the sites/all/profiles directory and will take
-precedence over profiles in this directory. Alternatively, the
-sites/your_site_name/profiles directory pattern may be used to restrict a
-profile's availability to a specific site instance.
-
-Additionally, modules and themes may be placed inside subdirectories in a
-specific installation profile such as profiles/your_site_profile/modules and
-profiles/your_site_profile/themes respectively to restrict their usage to only
-sites that were installed with that specific profile.
-
-Refer to the "Installation Profiles" section of the README.txt in the Drupal
-root directory for further information.
+Installation profiles define additional steps that run after the base
+installation provided by Drupal core when Drupal is first installed.
+
+WHAT TO PLACE IN THIS DIRECTORY?
+--------------------------------
+
+Place downloaded and custom installation profiles in this directory.
+Installation profiles are generally provided as part of a Drupal distribution.
+They only impact the installation of your site. They do not have any effect on
+an already running site.
+
+DOWNLOAD ADDITIONAL DISTRIBUTIONS
+---------------------------------
+
+Contributed distributions from the Drupal community may be downloaded at
+https://www.drupal.org/project/project_distribution.
+
+MULTISITE CONFIGURATION
+-----------------------
+
+In multisite configurations, installation profiles found in this directory are
+available to all sites during their initial site installation.
+
+MORE INFORMATION
+----------------
+
+Refer to the "Installation profiles" section of the README.txt in the Drupal
+root directory for further information on extending Drupal with custom profiles.

themes/README.txt

@@ -1,16 +1,31 @@
-Place downloaded and custom themes that modify your site's appearance in this
-directory to ensure clean separation from Drupal core and to facilitate safe,
-self-contained code updates. Contributed themes from the Drupal community may
-be downloaded at https://www.drupal.org/project/themes.
-
-It is safe to organize themes into subdirectories and is recommended to use
-Drupal's sub-theme functionality to ensure easy maintenance and upgrades.
-
-In multisite configuration, themes found in this directory are available to
-all sites. In addition to this directory, shared common themes may also be kept
-in the sites/all/themes directory and will take precedence over themes in this
-directory. Alternatively, the sites/your_site_name/themes directory pattern may
-be used to restrict themes to a specific site instance.
-
-Refer to the "Appearance" section of the README.txt in the Drupal root
-directory for further information on theming.
+Themes allow you to change the look and feel of your Drupal site. You can use
+themes contributed by others or create your own.
+
+WHAT TO PLACE IN THIS DIRECTORY?
+--------------------------------
+
+Placing downloaded and custom themes in this directory separates downloaded and
+custom themes from Drupal core's themes. This allows Drupal core to be updated
+without overwriting these files.
+
+DOWNLOAD ADDITIONAL THEMES
+--------------------------
+
+Contributed themes from the Drupal community may be downloaded at
+https://www.drupal.org/project/project_theme.
+
+MULTISITE CONFIGURATION
+-----------------------
+
+In multisite configurations, themes found in this directory are available to
+all sites. You may also put themes in the sites/all/themes directory, and the
+versions in sites/all/themes will take precedence over versions of the same
+themes that are here. Alternatively, the sites/your_site_name/themes directory
+pattern may be used to restrict themes to a specific site instance.
+
+MORE INFORMATION
+-----------------
+
+Refer to the "Appearance" section of the README.txt in the Drupal root directory
+for further information on customizing the appearance of Drupal with custom
+themes.