Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Mar 14, 2015
Merged

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

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
598e522
Updated documentation standards (code examples and English use)
javiereguiluz Mar 6, 2015
9c44351
Rewords, tweaks and fixes
javiereguiluz Mar 7, 2015
b96abbb
Reworded the paragraph about enforcing an English reference
javiereguiluz Mar 9, 2015
e5b6145
Improved the URL of the English reference dictionary
javiereguiluz Mar 9, 2015
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 20 additions & 3 deletions contributing/documentation/standards.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"when te code requires a vendor name"?

* The code should follow the :doc:`Symfony Best Practices </best_practices>`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The referenced document should probably be /best_practices/introduction.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Much better. Thanks.

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 </contributing/code/standards>`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would love to keep this standard (follow CS) the first item in the list.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree. Done.

as well as the `Twig Coding Standards`_;
* To avoid horizontal scrolling on code blocks, we prefer to break a line
Expand Down Expand Up @@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

-1 on this paragraph, I don't think it add much extra value. It is already clear that the docs use the American English dialect and the fact that English doesn't have a central language authority isn't really important.

However, +1 for including a link to the AE Oxford Dictionary

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You are right. I've reworded the entire thing as follows:

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.


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 Uncyclopedia article about `headings and titles`_).
Expand All @@ -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/
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This page doesn't seem like the best choice to me. At least, when I search for words there, I am asked to purchase a subscription to use their service.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The problem is that I can't find a direct link to the American English dictionary. The given URL is correct (at least for me) but you have to do several things to look for a word:

dictionary

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should link to http://www.oxforddictionaries.com/definition/american_english/ to set the language to ENG (US).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've just updated the URL to use the one you suggest.

.. _`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