minor #5064 Updated documentation standards (code examples and English use) (javiereguiluz)

weaverryan · weaverryan · commit dc010766dff6 · 2015-03-14T14:40:43.000-04:00
This PR was merged into the 2.3 branch. Discussion ---------- Updated documentation standards (code examples and English use) | Q | A | ------------- | --- | Doc fix? | no | New docs? | yes | Applies to | all | Fixed tickets | - This PR includes two changes: * Recommendations to create better code examples. * Detailed explanation about our English usage and what to do in case of disputes. Commits ------- e5b6145 Improved the URL of the English reference dictionary b96abbb Reworded the paragraph about enforcing an English reference 9c44351 Rewords, tweaks and fixes 598e522 Updated documentation standards (code examples and English use)
diff --git a/contributing/documentation/standards.rst b/contributing/documentation/standards.rst
@@ -8,7 +8,8 @@ Sphinx
 ------
 
 * The following characters are chosen for different heading levels: level 1
-  is ``=``, level 2 ``-``, level 3 ``~``, level 4 ``.`` and level 5 ``"``;
+  is ``=`` (equal sign), level 2 ``-`` (dash), level 3 ``~`` (tilde), level 4
+  ``.`` (dot) and level 5 ``"`` (double quote);
 * Each line should break approximately after the first word that crosses the
   72nd character (so most lines end up being 72-78 characters);
 * The ``::`` shorthand is *preferred* over ``.. code-block:: php`` to begin a PHP
@@ -50,6 +51,12 @@ Code Examples
 
 * The code follows the :doc:`Symfony Coding Standards </contributing/code/standards>`
   as well as the `Twig Coding Standards`_;
+* The code examples should look real for a web application context. Avoid abstract
+  or puerile examples (``foo``, ``bar``, ``demo``, etc.);
+* The code should follow the :doc:`Symfony Best Practices </best_practices/introduction>`.
+  Unless the example requires to use a custom bundle, make sure to always use the
+  ``AppBundle`` bundle to store your code;
+* Use ``Acme`` when the code requires a vendor name;
 * To avoid horizontal scrolling on code blocks, we prefer to break a line
   correctly if it crosses the 85th character;
 * When you fold one or more lines of code, place ``...`` in a comment at the point
@@ -140,8 +147,12 @@ Files and Directories
 English Language Standards
 --------------------------
 
-* **English Dialect**: use the United States English dialect, commonly called
-  `American English`_.
+Symfony documentation uses the United States English dialect, commonly called
+`American English`_. The `American English Oxford Dictionary`_ is used as the
+vocabulary reference.
+
+In addition, documentation follows these rules:
+
 * **Section titles**: use a variant of the title case, where the first
   word is always capitalized and all other words are capitalized, except for
   the closed-class words (read Wikipedia article about `headings and titles`_).
@@ -164,6 +175,7 @@ English Language Standards
 .. _`the Sphinx documentation`: http://sphinx-doc.org/rest.html#source-code
 .. _`Twig Coding Standards`: http://twig.sensiolabs.org/doc/coding_standards.html
 .. _`American English`: http://en.wikipedia.org/wiki/American_English
+.. _`American English Oxford Dictionary`: http://www.oxforddictionaries.com/definition/american_english/
 .. _`headings and titles`: http://en.wikipedia.org/wiki/Letter_case#Headings_and_publication_titles
 .. _`Serial (Oxford) Commas`: http://en.wikipedia.org/wiki/Serial_comma
 .. _`nosism`: http://en.wikipedia.org/wiki/Nosism
