Updates to language on The Big Picture

quick_tour/the_big_picture.rst

@@ -1,12 +1,11 @@
 The Big Picture
 ===============
 
-So, you want to try out Symfony2 but only have 10 minutes or so? This first
-part of this tutorial has been written for you. It explains how to get started
-fast with Symfony2 by showing you the structure of a simple ready-made
-project.
+Start using Symfony2 in 10 minutes! This tutorial contains some important
+concepts behind Symfony2. It explains how to get started quickly by showing you
+the structure of a sample project.
 
-If you have ever used a web framework before, you should feel right at home
+If you have used a web framework before, you should feel right at home
 with Symfony2.
 
 .. index::
@@ -15,15 +14,14 @@ with Symfony2.
 Downloading and Installing Symfony2
 -----------------------------------
 
-First, check that you have at least PHP 5.3.2 installed and correctly
-configured to work with a web server like Apache.
+First, check that you have installed and configured a webserver (such as
+Apache) with PHP 5.3.2 or higher.
 
 Ready? Let's start by downloading Symfony2. To get started even faster, we are
-going to use the "Symfony2 sandbox". It is a Symfony2 project where all the
-required libraries and some simple controllers are already included; the basic
-configuration is also already done. The great advantage of the sandbox over
-other types of installation is that you can start experimenting with Symfony2
-immediately.
+going to use the "Symfony2 sandbox". This is a preconfigured Symfony2 project
+that includes some simple controllers and their required libraries. The great
+advantage of the sandbox over other methods of installation is you can start
+experimenting with Symfony2 immediately.
 
 Download the `sandbox`_, and unpack it in your root web directory. You
 should now have a ``sandbox/`` directory::
@@ -51,25 +49,35 @@ should now have a ``sandbox/`` directory::
 Checking the Configuration
 --------------------------
 
-To avoid some headaches further down the line, check that your configuration
-can run a Symfony2 project smoothly by requesting the following URL:
+Symfony2 comes with a visual server configuration tester to help avoid some 
+headaches that come from web server or php misconfiguration. Please use 
+the following url to see the diagnostics for your server:
 
     http://localhost/sandbox/web/check.php
 
-Read the script output carefully and fix any problem that it finds.
+Read the script output carefully and correct any oustanding issues. 
 
-Now, request your first "real" Symfony2 webpage:
+Now you can request your first "real" Symfony2 webpage:
 
     http://localhost/sandbox/web/app_dev.php/
 
 Symfony2 should congratulate you for your hard work so far!
 
+.. tip::
+
+    On production servers, you should point your web root directory to the
+    ``web/`` directory to secure your installation and have an even better
+    looking URL:
+
+    http://localhost/hello/Fabien
+
+
 Creating your first Application
 -------------------------------
 
-The sandbox comes with a simple Hello World ":term:`application`" and that's
-the application we will use to learn more about Symfony2. Go to the following
-URL to be greeted by Symfony2 (replace Fabien with your first name):
+The sandbox comes with a simple Hello World ":term:`application`" we will use
+to learn more about Symfony2. Go to the following URL to be greeted by Symfony2
+(replace Fabien with your first name):
 
     http://localhost/sandbox/web/app_dev.php/hello/Fabien
 
@@ -80,7 +88,7 @@ What's going on here? Let's dissect the URL:
 * ``app_dev.php``: This is a "front controller". It is the unique entry point
   of the application and it responds to all user requests;
 
-* ``/hello/Fabien``: This is the "virtual" path to the resource the user wants
+* ``/hello/Fabien``: This is the virtual path to the resource the user wants
   to access.
 
 Your responsibility as a developer is to write the code that maps the user
@@ -93,19 +101,14 @@ Fabien!``).
 Configuration
 ~~~~~~~~~~~~~
 
-But how does Symfony2 route the request to your code? Simply by reading some
-configuration file.
-
-All Symfony2 configuration files can be written in either PHP, XML, or `YAML`_
-(YAML is a simple format that makes the description of configuration settings
-straightforward).
+Symfony2 configuration files can be written in PHP, XML or `YAML`_. The 
+different types are compatible and may be used interchangeably within an 
+application.
 
 .. tip::
 
     The sandbox defaults to YAML, but you can easily switch to XML or PHP by
-    editing the ``app/AppKernel.php`` file. You can switch now by looking at
-    the bottom of this file for instructions (the tutorials show the
-    configuration for all supported formats).
+    editing the ``app/AppKernel.php`` file.
 
 .. index::
    single: Routing
@@ -114,7 +117,8 @@ straightforward).
 Routing
 ~~~~~~~
 
-So, Symfony2 routes the request by reading the routing configuration file:
+Symfony2 routes the request to your code by using a configuration file. Here 
+are a few examples of the routing configuration file for our application:
 
 .. configuration-block::
 
@@ -158,9 +162,14 @@ So, Symfony2 routes the request by reading the routing configuration file:
 
         return $collection;
 
-The first few lines of the routing configuration file define the code called
-when the user requests the "``/``" resource. More interesting is the last
-part, which imports another routing configuration file that reads as follows:
+The first few lines of the routing configuration file define the code that is 
+executed when the user requests the "``/``" resource. 
+
+.. tip::
+
+   If you're comfortable with routing, have a look at the last directive of 
+   the configuration file. Symfony2 can include routing information from 
+   other bundles. 
 
 .. configuration-block::
 
@@ -198,7 +207,7 @@ part, which imports another routing configuration file that reads as follows:
 
         return $collection;
 
-Here we go! As you can see, the "``/hello/{name}``" resource pattern (a string
+As you can see, the "``/hello/{name}``" resource pattern (a string
 enclosed in curly brackets like ``{name}`` is a placeholder) is mapped to a
 controller, referenced by the ``_controller`` value.
 
@@ -209,8 +218,8 @@ controller, referenced by the ``_controller`` value.
 Controllers
 ~~~~~~~~~~~
 
-The controller is responsible for returning a representation of the resource
-(most of the time an HTML one) and it is defined as a PHP class:
+The controller defines actions to handle users requests and prepares responses
+(often in HTML).
 
 .. code-block:: php
    :linenos:
@@ -234,21 +243,22 @@ The controller is responsible for returning a representation of the resource
 
 The code is pretty straightforward but let's explain it line by line:
 
-* *line 3*: Symfony2 takes advantage of new PHP 5.3 features and as such, all
-  controllers are properly namespaced (the namespace is the first part of the
-  ``_controller`` routing value: ``HelloBundle``).
+* *line 3*: Symfony2 takes advantage of new PHP 5.3 namespacing features, and
+  all controllers should be properly namespaced. Per the routing file above,
+  the namespace is the first part of the ``_controller`` routing value:
+  ``HelloBundle``).
 
-* *line 7*: The controller name is the concatenation of the second part of the
-  ``_controller`` routing value (``Hello``) and ``Controller``. It extends the
-  built-in ``Controller`` class, which provides useful shortcuts (as we will
-  see later in this tutorial).
+* *line 7*: The controller name is the combination of the second part of the
+  ``_controller`` routing value  (``Hello``) and the word ``Controller``. It
+  extends the built-in ``Controller`` class, which provides useful shortcuts
+  (as we will see later in this tutorial).
 
-* *line 9*: Each controller is made of several actions. As per the
+* *line 9*: Each controller is made of several actions. As per the routing
   configuration, the hello page is handled by the ``index`` action (the third
   part of the ``_controller`` routing value). This method receives the
-  resource placeholder values as arguments (``$name`` in our case).
+  placeholder values as arguments (``$name`` in our case).
 
-* *line 11*: The ``render()`` method loads and renders a template
+* *line 11*: The ``render()`` method loads and renders a template file
   (``HelloBundle:Hello:index.html.twig``) with the variables passed as a
   second argument.
 
@@ -258,13 +268,18 @@ organized in bundles. In Symfony2 speak, a bundle is a structured set of files
 feature (a blog, a forum, ...) and which can be easily shared with other
 developers. In our example, we only have one bundle, ``HelloBundle``.
 
+.. tip::
+
+    In general, controller actions should be as short as possible. If one is
+    getting too long, consider refactoring some of the more complicated code to
+    the service layer (which will be discussed later).
+
 Templates
 ~~~~~~~~~
 
-So, the controller renders the ``HelloBundle:Hello:index.html.twig`` template.
-But what's in a template name? ``HelloBundle`` is the bundle name, ``Hello``
-is the controller, and ``index.html.twig`` the template name. By default, the
-sandbox uses Twig as its template engine:
+The controller renders the ``HelloBundle:Hello:index.html.twig`` template. By 
+default, the sandbox uses Twig as its template engine but you can also use
+traditional PHP templates if you choose.
 
 .. code-block:: jinja
 
@@ -275,24 +290,19 @@ sandbox uses Twig as its template engine:
         Hello {{ name }}!
     {% endblock %}
 
-Congratulations! You have looked at your first Symfony2 piece of code. That was
-not so hard, was it? Symfony2 makes it really easy to implement web sites
-better and faster.
-
 .. index::
    single: Environment
    single: Configuration; Environment
 
 Working with Environments
 -------------------------
 
-Now that you have a better understanding on how Symfony2 works, have a closer
+Now that you have a better understanding of how Symfony2 works, have a closer
 look at the bottom of the page; you will notice a small bar with the Symfony2
-and PHP logos. It is called the "Web Debug Toolbar" and it is the developer's
+and PHP logos. This is called the "Web Debug Toolbar" and it is the developer's
 best friend. Of course, such a tool must not be displayed when you deploy your
-application to your production servers. That's why you will find another front
-controller in the ``web/`` directory (``app.php``), optimized for the
-production environment:
+application to production. That's why you will find another front controller in
+the ``web/`` directory (``app.php``), optimized for the production environment:
 
     http://localhost/sandbox/web/app.php/hello/Fabien
 
@@ -301,26 +311,19 @@ And if you use Apache with ``mod_rewrite`` enabled, you can even omit the
 
     http://localhost/sandbox/web/hello/Fabien
 
-Last but not least, on the production servers, you should point your web root
-directory to the ``web/`` directory to secure your installation and have an even
-better looking URL:
-
-    http://localhost/hello/Fabien
-
 To make the production environment as fast as possible, Symfony2 maintains a
 cache under the ``app/cache/`` directory. When you make changes to the code or
-configuration, you need to manually remove the cached files. That's why you
-should always use the development front controller (``app_dev.php``) when
-working on a project.
+configuration, you need to manually remove the cached files. The development
+front controller (``app_dev.php``) does not use this cache and your changes
+appear immediately, thus is recommended when working on a project.
 
 Final Thoughts
 --------------
 
-The 10 minutes are over. By now, you should be able to create your own simple
-routes, controllers, and templates. As an exercise, try to build something
-more useful than the Hello application! But if you are eager to learn more
-about Symfony2, you can read the next part of this tutorial right away, where
-we dive more into the templating system.
+Thanks for trying out Symfony2! By now, you should be able to create your own 
+simple routes, controllers and templates. As an exercise, try to build 
+something more useful than the Hello application! If you are eager to 
+learn more about Symfony2, dive into the next section: the view system.
 
 .. _sandbox: http://symfony-reloaded.org/code#sandbox
 .. _YAML:    http://www.yaml.org/