feature symfony#4223 Revamped the documentation about "Contributing Docs" (javiereguiluz)

This PR was merged into the 2.3 branch.

Discussion
----------

Revamped the documentation about "Contributing Docs"

| Q             | A
| ------------- | ---
| Doc fix?      | yes
| New docs?     | yes
| Applies to    | 2.3+
| Fixed tickets | -

This is the first step into completely revamping the *Contributing* section documentation. The main changes are:

  * A much more friendly and welcoming tone.
  * Thorough and step-by-step explanations that assumes no previous knowledge from the reader.
  * The use of real examples to illustrate the explanations, instead of using abstract concepts.
  * The old [Managing Releases](http://symfony.com/doc/current/contributing/documentation/overview.html#managing-releases) section has been completely removed. This has nothing to do with contributing documentations. It's just documentation for a process that only concerns to doc maintainers.

Commits
-------

88ddbb1 Fixed all the errors found by Ryan
baa06b5 Removed two highlight formats which are "experimental" and not used by end users
9bcd33d More and more fixes and improvements
15f3c94 Added another bunch of fixes suggested by reviewers
ff66e94 Added lots of fixes suggested by reviewers
991ff6f Added a note about not using relative internal links in the doc
79375ae Switched another relative link into an absolute reference
4751eb9 lways use absolute links instead of relative for internal doc links
53c3a16 Added missing link
723603c Revamped the documentation about "Contributing Docs"

Author: weaverryan

contributing/documentation/format.rst

@@ -1,17 +1,19 @@
 Documentation Format
 ====================
 
-The Symfony 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 Symfony `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,31 @@ 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
+===================  ======================================
 
 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 +134,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 the linked resource (``namespace``, ``class`` or ``method``):
 
 .. code-block:: rst
 
@@ -148,7 +166,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 +176,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

@@ -3,8 +3,8 @@
 Symfony Documentation License
 =============================
 
-The Symfony documentation is licensed under a Creative Commons
-Attribution-Share Alike 3.0 Unported `License`_.
+The Symfony2 documentation is licensed under a Creative Commons
+Attribution-Share Alike 3.0 Unported License (`CC BY-SA 3.0`_).
 
 **You are free:**
 
@@ -48,5 +48,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