tweaks to the contribution chapter

Author: xabbuh

contributing/documentation/format.rst

@@ -33,24 +33,15 @@ roles to the standard reST markup. Read more about the `Sphinx Markup Constructs
 Syntax Highlighting
 ~~~~~~~~~~~~~~~~~~~
 
-PHP is the default syntax highlight applied to all code blocks. You can change
-it with the ``code-block`` directive:
+PHP is the default syntax highlighter applied to all code blocks. You can
+change it with the ``code-block`` directive:
 
 .. code-block:: rst
 
     .. code-block:: yaml
 
         { foo: bar, bar: { foo: bar, bar: baz } }
 
-If your PHP code begins with ``<?php``, then you need to use ``html+php`` as
-the name of the highlighted syntax:
-
-.. code-block:: rst
-
-    .. code-block:: html+php
-
-        <?php echo $this->foobar(); ?>
-
 .. note::
 
     Besides all of the major programming languages, the syntax highlighter
@@ -183,7 +174,7 @@ If you're documenting a brand new feature or a change that's been made in
 Symfony, you should precede your description of the change with a
 ``.. versionadded:: 2.X`` directive and a short description:
 
-.. code-block:: text
+.. code-block:: rst
 
     .. versionadded:: 2.3
         The ``askHiddenResponse`` method was introduced in Symfony 2.3.
@@ -193,7 +184,7 @@ Symfony, you should precede your description of the change with a
 If you're documenting a behavior change, it may be helpful to *briefly* describe
 how the behavior has changed.
 
-.. code-block:: text
+.. code-block:: rst
 
     .. versionadded:: 2.3
         The ``include()`` function is a new Twig feature that's available in

contributing/documentation/overview.rst

@@ -3,10 +3,10 @@ Contributing to the Documentation
 
 One of the essential principles of the Symfony project is that **documentation is
 as important as code**. That's why a great amount of resources are dedicated to
-documenting new features and to keeping the rest of the documentation up to date.
+documenting new features and to keeping the rest of the documentation up-to-date.
 
-More than 800 developers all around the world have contributed to Symfony's
-documentation, and we are glad that you are considering joining this big family.
+More than 700 developers all around the world have contributed to Symfony's
+documentation and we are glad that you are considering joining this big family.
 This guide will explain everything you need to contribute to the Symfony
 documentation.
 
@@ -27,9 +27,9 @@ Before Your First Contribution
 Your First Documentation Contribution
 -------------------------------------
 
-In this section you'll learn how to contribute to the Symfony documentation for
+In this section, you'll learn how to contribute to the Symfony documentation for
 the first time. The next section will explain the shorter process you'll follow
-in the future for every contribution after your first.
+in the future for every contribution after your first one.
 
 Let's imagine that you want to improve the installation chapter of the Symfony
 book. In order to make your changes, follow these steps:
@@ -167,6 +167,19 @@ Now you can **sync your fork** by executing the following command:
     $ git checkout master
     $ git merge upstream/master
 
+.. note::
+
+    If you are documenting a feature based on another branch than master,
+    you'll also have to sync that branch. For example, if your changes will
+    be based on the 2.3 branch, execute the following commands:
+
+    .. code-block:: bash
+
+        $ cd projects/symfony-docs/
+        $ git fetch upstream
+        $ git checkout 2.3
+        $ git merge upstream/2.3
+
 Great! Now you can proceed by following the same steps explained in the previous
 section: