Reworded the introduction of the contributing docs #7873
Closed
Conversation
This file contains hidden or 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
|
I forgot to publish the "after" screenshot:
|
xabbuh
reviewed
May 5, 2017
contributing/documentation/index.rst
Outdated
| @@ -1,13 +1,30 @@ | |||
| Contributing Documentation | |||
| ========================== | |||
|
|
|||
| .. toctree:: | |||
| :maxdepth: 2 | |||
| Documentation is as important as code for Open Source projects. That's why | |||
xabbuh
reviewed
May 5, 2017
contributing/documentation/index.rst
Outdated
| Symfony dedicates a great amount of resources to document new features and to | ||
| keep the rest of the documentation up-to-date. | ||
|
|
||
| More than 1,000 developers have contributed to Symfony documentation and we are |
There was a problem hiding this comment.
Usually, we avoid the first person perspective. But here it matches quite well IMO.
xabbuh
reviewed
May 5, 2017
contributing/documentation/index.rst
Outdated
|
|
||
| :doc:`The Contribution Process </contributing/documentation/overview>` | ||
| Explains the steps to follow to contribute fixes and new contents. It follows | ||
| the standard GitHub contribution process of most Open Source projects, so you |
xabbuh
reviewed
May 5, 2017
contributing/documentation/index.rst
Outdated
| may already know everything that is needed. | ||
|
|
||
| :doc:`Documentation Formats </contributing/documentation/format>` | ||
| Explains the technical details of the reStructuredText format used to write |
xabbuh
reviewed
May 5, 2017
contributing/documentation/index.rst
Outdated
|
|
||
| :doc:`Documentation Formats </contributing/documentation/format>` | ||
| Explains the technical details of the reStructuredText format used to write | ||
| the docs. Skip it if you already are familiar with this format. |
There was a problem hiding this comment.
[...] if you are already familiar [...]
xabbuh
reviewed
May 5, 2017
contributing/documentation/index.rst
Outdated
|
|
||
| :doc:`Documentation Standards </contributing/documentation/standards>` | ||
| Explains how to write docs and code examples to match the style and tone of | ||
| the rest of the documentation. |
There was a problem hiding this comment.
[...] of the existing documentation?
xabbuh
reviewed
May 5, 2017
contributing/documentation/index.rst
Outdated
| standards | ||
| license | ||
| :doc:`License </contributing/documentation/license>` | ||
| Explains the details of the Creative Commons BB-SA 3.0 license used by the |
xabbuh
reviewed
May 5, 2017
contributing/documentation/index.rst
Outdated
| license | ||
| :doc:`License </contributing/documentation/license>` | ||
| Explains the details of the Creative Commons BB-SA 3.0 license used by the | ||
| Symfony Documentation. |
xabbuh
reviewed
May 5, 2017
| In order to help the reader as much as possible and to create code examples that | ||
| look and feel familiar, you should follow these standards. | ||
| Contributions must follow these standards to match the style and tone of the | ||
| rest of the Symfony Documentation. |
xabbuh
approved these changes
May 8, 2017
|
Thank you Javier. |
xabbuh
added a commit
that referenced
this pull request
May 12, 2017
…reguiluz) This PR was squashed before being merged into the 2.7 branch (closes #7873). Discussion ---------- Reworded the introduction of the contributing docs I propose a more gentle and actionable introduction to the "contributing docs" guide. The current introduction is confusing and intimidating to newcomers:  Commits ------- 6e23024 Reworded the introduction of the contributing docs
xabbuh
added a commit
that referenced
this pull request
May 12, 2017
xabbuh
added a commit
that referenced
this pull request
May 18, 2017
* 2.7: (21 commits) Update optional_dependencies.rst Fix xml blocks [#7875] minor tweaks Minor fix Minor changes [#7773] fix line length Add helpful remarks on custom DataCollector Remove use of deprecated security.exception_listener.class parameter Update resources.rst Fix incoherent ut8mb4 collation in Doctrine setup Fix decorating service definition fix empty XML element [#7873] add missing toctree entries Reworded the introduction of the contributing docs [HttpFoundation] Fix clearstatcache first arg Explain how to provide a stack trace Add link to the Slack support channel Mentioned FOSRestBundle's content negotiation Used the article example consistently in the example Update formats.rst ...
xabbuh
added a commit
that referenced
this pull request
May 18, 2017
* 2.8: (24 commits) Update optional_dependencies.rst Fix xml blocks pass only strings to loadUserByUsername() Fix Authenticator Class (getCredentials) example Added the picture that shows how GuardAuthenticationListener calls Authentication Guard methods. [#7875] minor tweaks Minor fix Minor changes [#7773] fix line length Add helpful remarks on custom DataCollector Remove use of deprecated security.exception_listener.class parameter Update resources.rst Fix incoherent ut8mb4 collation in Doctrine setup Fix decorating service definition fix empty XML element [#7873] add missing toctree entries Reworded the introduction of the contributing docs [HttpFoundation] Fix clearstatcache first arg Explain how to provide a stack trace Add link to the Slack support channel ...
weaverryan
added a commit
that referenced
this pull request
May 20, 2017
* origin/2.7: (51 commits) Avoid backticks in shell scripts Update optional_dependencies.rst Fix xml blocks [#7875] minor tweaks Minor fix Minor changes [#7773] fix line length Add helpful remarks on custom DataCollector Remove use of deprecated security.exception_listener.class parameter Update resources.rst Fix incoherent ut8mb4 collation in Doctrine setup Fix decorating service definition fix empty XML element [#7873] add missing toctree entries Reworded the introduction of the contributing docs [#7844] add XML and PHP config examples Property access [HttpFoundation] Fix clearstatcache first arg Explain how to provide a stack trace fix remaining setDefinition() call ...
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.
I propose a more gentle and actionable introduction to the "contributing docs" guide. The current introduction is confusing and intimidating to newcomers: