Rewordings, fixes and tweaks

Author: javiereguiluz

cookbook/bundles/best_practices.rst

@@ -69,12 +69,14 @@ class name.
 
 Each bundle has an alias, which is the lower-cased short version of the bundle
 name using underscores (``acme_blog`` for ``AcmeBlogBundle``). This alias
-is used to enforce uniqueness within a bundle (see below for some usage examples).
+is used to enforce uniqueness within a bundle and for defining its configuration
+(see below for some usage examples).
 
 Directory Structure
 -------------------
 
-The basic directory structure of a AcmeBlogBundle must read as follows:
+The basic directory structure of an AcmeBlogBundle must read as follows (if you
+use `PSR-4`_ the ``Acme/`` and ``BlogBundle/`` folders might not exist):
 
 .. code-block:: text
 
@@ -85,6 +87,7 @@ The basic directory structure of a AcmeBlogBundle must read as follows:
           └─ BlogBundle/
               ├─ AcmeBlogBundle.php
               ├─ Controller/
+              ├─ README.md
               ├─ Resources/
               │   ├─ meta/
               │   │  └─ LICENSE
@@ -101,7 +104,11 @@ that automated tools can rely on:
 
 * ``AcmeBlogBundle.php``: This is the class that transforms a plain directory
   into a Symfony bundle;
-* ``Resources/meta/LICENSE``: The full license for the code;
+* ``README.md``: This file contains the basic description of the bundle and it
+  usually shows some basic examples and links to its full documentation;
+* ``Resources/meta/LICENSE``: The full license for the code. The license file
+  can also be stored in the bundle's root directory to follow the generic
+  conventions about packages;
 * ``Resources/doc/index.rst``: The root file for the Bundle documentation.
 
 The depth of sub-directories should be kept to the minimum for most used
@@ -301,12 +308,6 @@ The end user can provide values in any configuration file:
         // app/config/config.php
         $container->setParameter('acme_blog.author.email', 'fabien@example.com');
 
-    .. code-block:: ini
-
-        ; app/config/config.ini
-        [parameters]
-        acme_blog.author.email = fabien@example.com
-
 Retrieve the configuration parameters in your code from the container::
 
     $container->getParameter('acme_blog.author.email');
@@ -319,7 +320,7 @@ Services
 
 If the bundle defines services, they must be prefixed with the bundle alias.
 For an AcmeBlogBundle for instance, all services must be prefixed with
-``acme_blog_``.
+``acme_blog``.
 
 In addition, services not meant to be used by the application directly, should
 be :ref:`defined as private <container-private-services>`.