Revamped the documentation about "Contributing Docs"

contributing/documentation/format.rst

@@ -1,17 +1,19 @@
 Documentation Format
 ====================
 
-The Symfony2 documentation uses `reStructuredText`_ as its markup language and
-`Sphinx`_ for building the output (HTML, PDF, ...).
+The Symfony documentation uses reStructuredText_ as its markup language and
+Sphinx_ for generating the documentation in the formats read by the end users,
+such as HTML and PDF.
 
 reStructuredText
 ----------------
 
-reStructuredText *"is an easy-to-read, what-you-see-is-what-you-get plaintext
-markup syntax and parser system"*.
+reStructuredText is a plaintext markup syntax similar to Markdown, but much
+stricter with its syntax. If you are new to reStructuredText, take some time to
+familiarize with this format by reading the existing `Symfony documentation`_
 
-You can learn more about its syntax by reading existing Symfony2 `documents`_
-or by reading the `reStructuredText Primer`_ on the Sphinx website.
+If you want to learn more about this format, check out the `reStructuredText Primer`_
+tutorial and the `reStructuredText Reference`_.
 
 .. caution::
 
@@ -24,14 +26,14 @@ or by reading the `reStructuredText Primer`_ on the Sphinx website.
 Sphinx
 ------
 
-Sphinx is a build system that adds some nice tools to create documentation
-from reStructuredText documents. As such, it adds new directives and
-interpreted text roles to the standard reST `markup`_.
+Sphinx is a build system that provides tools to create documentation from
+reStructuredText documents. As such, it adds new directives and interpreted text
+roles to the standard reST markup. Read more about the `Sphinx Markup Constructs`_.
 
 Syntax Highlighting
 ~~~~~~~~~~~~~~~~~~~
 
-All code examples uses PHP as the default highlighted language. You can change
+PHP is the default syntax highlight applied to all code blocks. You can change
 it with the ``code-block`` directive:
 
 .. code-block:: rst
@@ -41,7 +43,7 @@ it with the ``code-block`` directive:
         { foo: bar, bar: { foo: bar, bar: baz } }
 
 If your PHP code begins with ``<?php``, then you need to use ``html+php`` as
-the highlighted pseudo-language:
+the name of the highlighted syntax:
 
 .. code-block:: rst
 
@@ -51,16 +53,18 @@ the highlighted pseudo-language:
 
 .. note::
 
-    A list of supported languages is available on the `Pygments website`_.
+    Besides all of the major programming languages, the syntax highlighter
+    supports all kinds of markup and configuration languages. Check out the
+    list of `supported languages`_ on the syntax highlighter website.
 
 .. _docs-configuration-blocks:
 
 Configuration Blocks
 ~~~~~~~~~~~~~~~~~~~~
 
-Whenever you show a configuration, you must use the ``configuration-block``
+Whenever you include a configuration sample, use the ``configuration-block``
 directive to show the configuration in all supported configuration formats
-(``PHP``, ``YAML``, and ``XML``)
+(``PHP``, ``YAML`` and ``XML``). Example:
 
 .. code-block:: rst
 
@@ -96,32 +100,33 @@ The previous reST snippet renders as follow:
 
 The current list of supported formats are the following:
 
-===============  ==============
-Markup format    Displayed
-===============  ==============
-html             HTML
-xml              XML
-php              PHP
-yaml             YAML
-jinja            Twig
-html+jinja       Twig
-html+php         PHP
-ini              INI
-php-annotations  Annotations
-php-standalone   Standalone Use
-php-symfony      Framework Use
-===============  ==============
+===================  ======================================
+Markup format        Use it to display
+===================  ======================================
+``html``             HTML
+``xml``              XML
+``php``              PHP
+``yaml``             YAML
+``jinja``            Pure Twig markup
+``html+jinja``       Twig markup blended with HTML
+``html+php``         PHP code blended with HTML
+``ini``              INI
+``php-annotations``  PHP Annotations
+``php-standalone``   Pure PHP code
+``php-symfony``      PHP code with special Symfony features
+===================  ======================================
 
 Adding Links
 ~~~~~~~~~~~~
 
-To add links to other pages in the documents use the following syntax:
+The most common type of links are **internal links** to other documentation pages,
+which use the following syntax:
 
 .. code-block:: rst
 
-    :doc:`/path/to/page`
+    :doc:`/absolute/path/to/page`
 
-Using the path and filename of the page without the extension, for example:
+The page name should not include the file extension (``.rst``). For example:
 
 .. code-block:: rst
 
@@ -131,14 +136,29 @@ Using the path and filename of the page without the extension, for example:
 
     :doc:`/cookbook/configuration/environments`
 
-The link text will be the main heading of the document linked to. You can
-also specify alternative text for the link:
+The title of the linked page will be automatically used as the text of the link.
+If you want to modify that title, use this alternative syntax:
 
 .. code-block:: rst
 
     :doc:`Spooling Email </cookbook/email/spool>`
 
-You can also add links to the API documentation:
+.. note::
+
+    Although they are technically correct, avoid the use of relative internal
+    links such as the following, because they break the references in the
+    generated PDF documentation:
+
+    .. code-block:: rst
+
+        :doc:`controller`
+
+        :doc:`event_dispatcher/introduction`
+
+        :doc:`environments`
+
+**Links to the API** follow a different syntax, where you must specify the type
+of linked resource (``namespace``, ``class`` or ``method``):
 
 .. code-block:: rst
 
@@ -148,7 +168,7 @@ You can also add links to the API documentation:
 
     :method:`Symfony\\Component\\HttpKernel\\Bundle\\Bundle::build`
 
-and to the PHP documentation:
+**Links to the PHP documentation** follow a pretty similar syntax:
 
 .. code-block:: rst
 
@@ -158,20 +178,55 @@ and to the PHP documentation:
 
     :phpfunction:`iterator_to_array`
 
-Testing Documentation
-~~~~~~~~~~~~~~~~~~~~~
+New Features or Behavior Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To test documentation before a commit:
+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:
 
-* Install `Sphinx`_;
-* Install the Sphinx extensions using git submodules: ``git submodule update --init``;
-* (Optionally) Install the bundle docs and CMF docs: ``bash install.sh``;
-* Run ``make html`` and view the generated HTML in the ``build`` directory.
+.. code-block:: text
+
+    .. versionadded:: 2.3
+        The ``askHiddenResponse`` method was introduced in Symfony 2.3.
+
+    You can also ask a question and hide the response. This is particularly [...]
+
+If you're documenting a behavior change, it may be helpful to *briefly* describe
+how the behavior has changed.
+
+.. code-block:: text
+
+    .. versionadded:: 2.3
+        The ``include()`` function is a new Twig feature that's available in
+        Symfony 2.3. Prior, the ``{% include %}`` tag was used.
+
+Whenever a new minor version of Symfony is released (e.g. 2.4, 2.5, etc),
+a new branch of the documentation is created from the ``master`` branch.
+At this point, all the ``versionadded`` tags for Symfony versions that have
+reached end-of-life will be removed. For example, if Symfony 2.5 were released
+today, and 2.2 had recently reached its end-of-life, the 2.2 ``versionadded``
+tags would be removed from the new 2.5 branch.
+
+Testing Documentation
+~~~~~~~~~~~~~~~~~~~~~
 
-.. _reStructuredText:        http://docutils.sourceforge.net/rst.html
-.. _Sphinx:                  http://sphinx-doc.org/
-.. _documents:               https://github.com/symfony/symfony-docs
-.. _reStructuredText Primer: http://sphinx-doc.org/rest.html
-.. _markup:                  http://sphinx-doc.org/markup/
-.. _Pygments website:        http://pygments.org/languages/
-.. _Sphinx quick setup:      http://sphinx-doc.org/tutorial.html#setting-up-the-documentation-sources
+When submitting a new content to the documentation repository or when changing
+any existing resource, an automatic process will check if your documentation is
+free of syntax errors and is ready to be reviewed.
+
+Nevertheless, if you prefer to do this check locally on your own machine before
+submitting your documentation, follow these steps:
+
+* Install Sphinx_;
+* Install the Sphinx extensions using git submodules: ``$ git submodule update --init``;
+* (Optionally) Install the bundle docs and CMF docs: ``$ bash install.sh``;
+* Run ``make html`` and view the generated HTML in the ``build/`` directory.
+
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+.. _Sphinx: http://sphinx-doc.org/
+.. _`Symfony documentation`: https://github.com/symfony/symfony-docs
+.. _`reStructuredText Primer`: http://sphinx-doc.org/rest.html
+.. _`reStructuredText Reference`: http://docutils.sourceforge.net/docs/user/rst/quickref.html
+.. _`Sphinx Markup Constructs`: http://sphinx-doc.org/markup/
+.. _`supported languages`: http://pygments.org/languages/

contributing/documentation/license.rst

@@ -2,7 +2,7 @@ Symfony2 Documentation License
 ==============================
 
 The Symfony2 documentation is licensed under a Creative Commons
-Attribution-Share Alike 3.0 Unported `License`_.
+Attribution-Share Alike 3.0 Unported License (`CC BY-SA 3.0`_).
 
 **You are free:**
 
@@ -46,5 +46,5 @@ Attribution-Share Alike 3.0 Unported `License`_.
 
 This is a human-readable summary of the `Legal Code (the full license)`_.
 
-.. _License: http://creativecommons.org/licenses/by-sa/3.0/
+.. _`CC BY-SA 3.0`: http://creativecommons.org/licenses/by-sa/3.0/
 .. _Legal Code (the full license): http://creativecommons.org/licenses/by-sa/3.0/legalcode