Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork5.2k
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.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Uh oh!
There was an error while loading.Please reload this page.
Conversation
| @@ -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; | |||
There was a problem hiding this comment.
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"?
| 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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
…h use) (javiereguiluz)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 dictionaryb96abbb Reworded the paragraph about enforcing an English reference9c44351 Rewords, tweaks and fixes598e522 Updated documentation standards (code examples and English use)
These all make good sense to me. Thanks Javier! |
* 2.3: (30 commits) [#5064] Minor language tweaks Switched the first example to a static constructor method added some more components for Tobion as a merger Fixed variable name in : Reference -> validation constraints -> count -> basic usage -> PHP [#5036] Typo fix (probably mine originally) caught by xabbuh reword to serves Adding a link to define "lts" Better wording Minor improvement for symfony-installer with LTS link to deciders' GitHub profiles Add missing use statement in Building Login Form doc Also removed use statement for Route as it is only needed when using annotations for routing Fixed incorrect plural form Improved the URL of the English reference dictionary Reworded the paragraph about enforcing an English reference enclose data type with double backticks Rewords, tweaks and fixes Updated documentation standards (code examples and English use) Added double backticks. And also a full stop. added link target/label in the cookbook Changed link into ref ...Conflicts:components/config/definition.rstcontributing/code/core_team.rstcookbook/security/form_login_setup.rst
* 2.6: (91 commits) [#5064] Minor language tweaks Fixing bad merge conflict (forgot to save!) Remove unnecessary component reference Correct RegisterListenersPass namespace Fix service id Switched the first example to a static constructor method added some more components for Tobion as a merger Fixed variable name in : Reference -> validation constraints -> count -> basic usage -> PHP [#5036] Typo fix (probably mine originally) caught by xabbuh reword to serves Adding a link to define "lts" Better wording Minor improvement for symfony-installer with LTS Updating for new security service names in 2.6 [#5033] Tweaking variable name to "match" the service id [#5017] Minor language tweaks [#5015] Updating the security service name for 2.6 - thanks to Cordoval [#5015] Very small tweak [#5011] Adding one more fix I missed [#5011] Fixing minor build issue ...Conflicts:book/security.rst
* 2.7: (103 commits) Backporting some stuff from 2.7, that I think must have gotten merged only there by accident [#5064] Minor language tweaks Fixing bad merge conflict (forgot to save!) Remove unnecessary component reference Correct RegisterListenersPass namespace Fix service id Switched the first example to a static constructor method added some more components for Tobion as a merger Fixed variable name in : Reference -> validation constraints -> count -> basic usage -> PHP [#5036] Typo fix (probably mine originally) caught by xabbuh reword to serves Adding a link to define "lts" Better wording Minor improvement for symfony-installer with LTS Updating for new security service names in 2.6 [#5033] Tweaking variable name to "match" the service id [#5017] Minor language tweaks [#5015] Updating the security service name for 2.6 - thanks to Cordoval [#5015] Very small tweak [#5011] Adding one more fix I missed ...
This PR includes two changes: