diff --git a/contributing/documentation/standards.rst b/contributing/documentation/standards.rst
index 39d073ec0da..e87e065c8ca 100644
--- 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 `
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 `.
+ 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
@@ -137,8 +144,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`_).
@@ -160,6 +171,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
pFad - Phonifier reborn
Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.
Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.
Alternative Proxies:
Alternative Proxy
pFad Proxy
pFad v3 Proxy
pFad v4 Proxy