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 2 commits
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
19 changes: 16 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 @@ -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
Expand Down Expand Up @@ -137,8 +144,13 @@ 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`_. 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.
Copy link
Member

Choose a reason for hiding this comment

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

I'm not sure if we need to be so strict here. Personally, I think that the sentence was fine before and we should just add a reference to the 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.

If you don't agree on this, I'll remove everything. The original idea was to provide a "protocol" to follow in case someone raises questions about uncommon words (refactorization, performant, front-end, etc.) I believe in providing clear rules and enforce them equally to everybody. But again, if you don't agree on this, let's remove it.

Copy link
Member

Choose a reason for hiding this comment

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

I don't think we need to formalize this section either. The standards should be quick and to the point. Imo, it's clear that the maintainers make the decisions when something is unclear and in any case, I doubt that I have more English knowledge than the PR author introducing words that aren't in the Oxford dictionary.

Copy link
Member

Choose a reason for hiding this comment

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

I agree. Furthermore, the more rules we have the more users might by scared away.

Copy link
Member Author

Choose a reason for hiding this comment

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

OK then. I've removed this section and left just the reference to the dictionary.


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 +172,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