From 598e522f3f68682e11fd3e4d418b2fd55eca77ae Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 6 Mar 2015 17:34:07 +0100 Subject: [PATCH 1/4] Updated documentation standards (code examples and English use) --- contributing/documentation/standards.rst | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/contributing/documentation/standards.rst b/contributing/documentation/standards.rst index 39d073ec0da..ce68e98d2a3 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 @@ -48,6 +49,12 @@ Example Code Examples ------------- +* The code examples should look real for a web application context. Avoid abstract + and puerile examples (``foo``, ``bar``, ``demo``, etc.); +* Use ``Acme`` when the code requires to explicit a vendor name; +* 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; * The code follows the :doc:`Symfony Coding Standards ` as well as the `Twig Coding Standards`_; * To avoid horizontal scrolling on code blocks, we prefer to break a line @@ -137,8 +144,17 @@ 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`_. + +Unlike most popular languages, the English language doesn't have a central +language authority and there is no official grammar or dictionary. Symfony +documentation uses the `American English Oxford Dictionary`_ to resolve disputes +over common words. In case a technical word isn't included in the dictionary yet, +Symfony Documentation maintainers will decide over the disputes. + +In addition, documentation contents should follow 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 +176,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/ .. _`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 From 9c443518b0f4ccd9f6301514f126b2af70754671 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sat, 7 Mar 2015 17:14:50 +0100 Subject: [PATCH 2/4] Rewords, tweaks and fixes --- contributing/documentation/standards.rst | 20 ++++++++------------ 1 file changed, 8 insertions(+), 12 deletions(-) diff --git a/contributing/documentation/standards.rst b/contributing/documentation/standards.rst index ce68e98d2a3..a0e1a611a4d 100644 --- a/contributing/documentation/standards.rst +++ b/contributing/documentation/standards.rst @@ -49,14 +49,14 @@ Example 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 - and puerile examples (``foo``, ``bar``, ``demo``, etc.); -* Use ``Acme`` when the code requires to explicit a vendor name; -* The code should follow the :doc:`Symfony Best Practices `. + 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; -* The code follows the :doc:`Symfony Coding Standards ` - as well as the `Twig Coding Standards`_; +* 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 @@ -145,13 +145,9 @@ English Language Standards -------------------------- Symfony documentation uses the United States English dialect, commonly called -`American English`_. - -Unlike most popular languages, the English language doesn't have a central -language authority and there is no official grammar or dictionary. Symfony -documentation uses the `American English Oxford Dictionary`_ to resolve disputes -over common words. In case a technical word isn't included in the dictionary yet, -Symfony Documentation maintainers will decide over the disputes. +`American English`_. Disputes over vocabulary will always be resolved using the +`American English Oxford Dictionary`_ reference. Disputes over neologisms not +included yet in the dictionary will be resolved by Symfony Documentation maintainers. In addition, documentation contents should follow these rules: From b96abbb3ae62a7ff23356bb44d17a2e2263b72f4 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 9 Mar 2015 11:59:33 +0100 Subject: [PATCH 3/4] Reworded the paragraph about enforcing an English reference --- contributing/documentation/standards.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/contributing/documentation/standards.rst b/contributing/documentation/standards.rst index a0e1a611a4d..db3e0624585 100644 --- a/contributing/documentation/standards.rst +++ b/contributing/documentation/standards.rst @@ -145,11 +145,10 @@ English Language Standards -------------------------- Symfony documentation uses the United States English dialect, commonly called -`American English`_. Disputes over vocabulary will always be resolved using the -`American English Oxford Dictionary`_ reference. Disputes over neologisms not -included yet in the dictionary will be resolved by Symfony Documentation maintainers. +`American English`_. The `American English Oxford Dictionary`_ is used as the +vocabulary reference. -In addition, documentation contents should follow these rules: +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 From e5b6145aaba6bd93e7bdc885eb2e60b4135f5df3 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 9 Mar 2015 12:00:22 +0100 Subject: [PATCH 4/4] Improved the URL of the English reference dictionary --- contributing/documentation/standards.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing/documentation/standards.rst b/contributing/documentation/standards.rst index db3e0624585..e87e065c8ca 100644 --- a/contributing/documentation/standards.rst +++ b/contributing/documentation/standards.rst @@ -171,7 +171,7 @@ In addition, documentation follows these rules: .. _`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/ +.. _`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