diff --git a/contributing/documentation/format.rst b/contributing/documentation/format.rst index f1c8031e62d..56fcbba574d 100644 --- a/contributing/documentation/format.rst +++ b/contributing/documentation/format.rst @@ -1,8 +1,8 @@ Documentation Format ==================== -The Symfony documentation uses reStructuredText_ as its markup language and -Sphinx_ for generating the documentation in the formats read by the end users, +The Symfony documentation uses `reStructuredText`_ as its markup language and +`Sphinx`_ for generating the documentation in the formats read by the end users, such as HTML and PDF. reStructuredText diff --git a/contributing/documentation/index.rst b/contributing/documentation/index.rst index e3711184813..769768311dd 100644 --- a/contributing/documentation/index.rst +++ b/contributing/documentation/index.rst @@ -1,13 +1,25 @@ Contributing Documentation ========================== -.. toctree:: - :maxdepth: 2 +These short articles explain everything you need to contribute to the Symfony +documentation: + +:doc:`The Contribution Process ` + Explains the steps to follow to contribute fixes and new contents. It's the + same contribution process followed by most open source projects, so you may + already know everything that is needed. + +:doc:`Documentation Formats ` + Explains the technical details of the reStructuredText format that is used to + write the docs. Skip it if you are already familiar with this format. + +:doc:`Documentation Standards ` + Explains how to write docs and code examples to match the style and tone of + the rest of the existing documentation. - overview - format - standards - license +:doc:`License ` + Explains the details of the Creative Commons BY-SA 3.0 license used for the + Symfony Documentation. .. toctree:: :hidden: diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst index 5efb5b9af81..c70d3c110b0 100644 --- a/contributing/documentation/overview.rst +++ b/contributing/documentation/overview.rst @@ -1,30 +1,16 @@ Contributing to the Documentation ================================= -One of the essential principles of the Symfony project is that **documentation -is as important as code**. That's why a great amount of resources are dedicated -to documenting new features and to keeping the rest of the documentation -up-to-date. - -More than 1,000 developers all around the world have contributed to Symfony's -documentation and we are glad that you are considering joining this big family. -This guide will explain everything you need to contribute to the Symfony -documentation. - Before Your First Contribution ------------------------------ -**Before contributing**, you should consider the following: - -* Symfony documentation is written using `reStructuredText`_ markup language. - If you are not familiar with this format, read - :doc:`this article ` for a quick overview - of its basic features. -* Symfony documentation is hosted on `GitHub`_. You'll need a free GitHub user - account to contribute to the documentation. -* Symfony documentation is published under a - :doc:`Creative Commons BY-SA 3.0 License ` - and all your contributions will implicitly adhere to that license. +**Before contributing**, you need to: + +* Sign up for a free `GitHub`_ account, which is the service where the Symfony + documentation is hosted. +* Be familiar with the `reStructuredText`_ markup language, which is used to + write Symfony docs. Read :doc:`this article ` + for a quick overview. .. _minor-changes-e-g-typos: diff --git a/contributing/documentation/standards.rst b/contributing/documentation/standards.rst index ee24b9bbb76..ec65cc08538 100644 --- a/contributing/documentation/standards.rst +++ b/contributing/documentation/standards.rst @@ -1,8 +1,8 @@ Documentation Standards ======================= -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. Sphinx ------ diff --git a/contributing/documentation/translations.rst b/contributing/documentation/translations.rst index c1be9f3b5ba..d4e911fc3db 100644 --- a/contributing/documentation/translations.rst +++ b/contributing/documentation/translations.rst @@ -1,7 +1,7 @@ Translations ============ -The Symfony documentation is not officially translated, though some community -groups still maintain some translations. For more information, see `this blog post`_. +The official Symfony documentation is published only in English, but some +community groups maintain `unofficial translations`_. -.. _`this blog post`: https://symfony.com/blog/discontinuing-the-symfony-community-translations +.. _`unofficial translations`: https://symfony.com/blog/discontinuing-the-symfony-community-translations