More and more fixes and improvements

Author: javiereguiluz

contributing/documentation/format.rst

@@ -1,8 +1,8 @@
 Documentation Format
 ====================
 
-The Symfony documentation uses `reStructuredText`_ as its markup language and
-`Sphinx`_ for generating the documentation in the formats read by the end users,
+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
@@ -12,7 +12,7 @@ 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`_
 
-If you prefer to learn more about this format, check out the `reStructuredText Primer`_
+If you want to learn more about this format, check out the `reStructuredText Primer`_
 tutorial and the `reStructuredText Reference`_.
 
 .. caution::
@@ -64,7 +64,7 @@ Configuration Blocks
 
 Whenever you include a configuration sample, use the ``configuration-block``
 directive to show the configuration in all supported configuration formats
-(``PHP``, ``YAML``, and ``XML``). Example:
+(``PHP``, ``YAML`` and ``XML``). Example:
 
 .. code-block:: rst
 
@@ -146,7 +146,8 @@ If you want to modify that title, use this alternative syntax:
 .. note::
 
     Although they are technically correct, avoid the use of relative internal
-    links such as the following:
+    links such as the following, because they break the references in the
+    generated PDF documentation:
 
     .. code-block:: rst
 
@@ -217,13 +218,13 @@ 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 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/
+.. _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

contributing/documentation/overview.rst

@@ -14,10 +14,10 @@ Before Your First Contribution
 
 **Before contributing**, you should consider the following:
 
-* Symfony documentation is written using `reStructuredText`_ markup language.
+* Symfony documentation is written using reStructuredText_ markup language.
   If you are not familiar with this format, read :doc:`this article </contributing/documentation/format>`
   for a quick overview of its basic features.
-* Symfony documentation is hosted on `GitHub`_. You'll need a GitHub user account
+* Symfony documentation is hosted on GitHub_. You'll need a GitHub user account
   to contribute documentation.
 * Symfony documentation is published under a
   :doc:`Creative Commons BY-SA 3.0 License </contributing/documentation/license>`
@@ -137,7 +137,7 @@ changes and push them:
 
 **Step 10.** After your pull request is eventually accepted and merged in the Symfony
 documentation, you will be included in the `Symfony Documentation Contributors`_
-list. Moreover, if you happen to have a `SensioLabsConnect`_ profile, you will
+list. Moreover, if you happen to have a SensioLabsConnect_ profile, you will
 get a cool `Symfony Documentation Badge`_.
 
 Your Second Documentation Contribution
@@ -286,16 +286,17 @@ which is the state of your work:
 Would You Admit a Huge Pull Request with Lots of Changes?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Sure! But before doing a huge change, it's probably a good idea to open an issue
-in the Symfony Documentation repository to ask the managers if they agree with
-your proposed changes. Otherwise, they could refuse your proposal after having
-made all the work and you would have wasted a lot of time.
+First, make sure that the changes are somewhat related. Otherwise, please create
+separate pull requests. Anyway, before submitting a huge change, it's probably a
+good idea to open an issue in the Symfony Documentation repository to ask the
+managers if they agree with your proposed changes. Otherwise, they could refuse
+your proposal after having made all the work and you would have wasted a lot of time.
 
 .. _`github.com/symfony/symfony-docs`: https://github.com/symfony/symfony-docs
-.. _`reStructuredText`: http://docutils.sourceforge.net/rst.html
-.. _`GitHub`: https://github.com/
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+.. _GitHub: https://github.com/
 .. _`fork the repository`: https://help.github.com/articles/fork-a-repo
 .. _`Symfony Documentation Contributors`: http://symfony.com/contributors/doc
-.. _`SensioLabsConnect`: https://connect.sensiolabs.com/
+.. _SensioLabsConnect: https://connect.sensiolabs.com/
 .. _`Symfony Documentation Badge`: https://connect.sensiolabs.com/badge/36/symfony-documentation-contributor
 .. _`sync your fork`: https://help.github.com/articles/syncing-a-fork

contributing/documentation/standards.rst

@@ -140,7 +140,7 @@ English Language Standards
 * **English Dialect**: use the United States English dialect, commonly called
   `American English`_.
 * **Section titles**: use a variant of the title case, where the first
-  word is always capitalized, and all other words are capitalized, except for
+  word is always capitalized and all other words are capitalized, except for
   the closed-class words (read Wikipedia article about `headings and titles`_).
 
   E.g.: The Vitamins are in my Fresh California Raisins

contributing/documentation/translations.rst

@@ -4,6 +4,12 @@ Translations
 The Symfony2 documentation is written in English and many people are involved
 in the translation process.
 
+.. note::
+
+    Symfony Project officially discourages starting new translations for the
+    documentation. As a matter of fact, there is `an ongoing discussion`_ in
+    the community about the benefits and drawbacks of community driven translations.
+
 Contributing
 ------------
 
@@ -84,4 +90,5 @@ repository and apply changes to the translated documents as soon as possible.
     Non maintained languages are removed from the official list of
     repositories as obsolete documentation is dangerous.
 
+.. _`an ongoing discussion`: https://github.com/symfony/symfony-docs/issues/4078
 .. _Symfony docs mailing-list: http://groups.google.com/group/symfony-docs