Updated documentation standards (code examples and English use) #5064
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| @@ -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.
"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.
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.
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.
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.
I agree. Furthermore, the more rules we have the more users might by scared away.
There was a problem hiding this comment.
OK then. I've removed this section and left just the reference to the dictionary.
weaverryan
added a commit
that referenced
this pull request
Mar 14, 2015
…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 dictionary b96abbb Reworded the paragraph about enforcing an English reference 9c44351 Rewords, tweaks and fixes 598e522 Updated documentation standards (code examples and English use)
weaverryan
added a commit
that referenced
this pull request
Mar 14, 2015
|
These all make good sense to me. Thanks Javier! |
weaverryan
added a commit
that referenced
this pull request
Mar 14, 2015
* 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.rst contributing/code/core_team.rst cookbook/security/form_login_setup.rst
weaverryan
added a commit
that referenced
this pull request
Mar 14, 2015
* 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
weaverryan
added a commit
that referenced
this pull request
Mar 14, 2015
* 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 ...
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR includes two changes: