From 49dda3753108f43c702f95bdff480a178aba52ff Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 4 May 2017 12:55:58 +0200 Subject: [PATCH 1/6] Reworded the introduction of the contributing docs --- contributing/documentation/format.rst | 4 +-- contributing/documentation/index.rst | 28 ++++++++++++++++----- contributing/documentation/overview.rst | 28 ++++++--------------- contributing/documentation/standards.rst | 4 +-- contributing/documentation/translations.rst | 6 ++--- 5 files changed, 36 insertions(+), 34 deletions(-) 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..7c6e4f67f79 100644 --- a/contributing/documentation/index.rst +++ b/contributing/documentation/index.rst @@ -1,13 +1,29 @@ Contributing Documentation ========================== -.. toctree:: - :maxdepth: 2 +Documentation is as important as code for Open Source projects. That's why +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 all around the world have contributed to Symfony +documentation and we are glad that you are considering joining this big family. +This guide will explain everything you need to contribute to the documentation: + +* :doc:`The Contribution Process `, + explains in detail the steps to follow to contribute fixes and new contents. + It follows the standard GitHub contribution process of most Open Source + projects, so you may already know everything that is needed. + +* :doc:`Formats `, explains the technical + details of the reStructuredText format used to write the docs. Skip it if + you already are familiar with this format. + +* :doc:`Standards `, explains how to + write docs and code examples to match the style and tone of the rest of the + documentation. - overview - format - standards - license +* :doc:`License `, explains the details of + the Creative Commons BB-SA 3.0 license used by 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..77cea866ad5 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 From 326541ab6246cbafa0a736968982e76a297fb411 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 4 May 2017 13:08:33 +0200 Subject: [PATCH 2/6] Use a definition list --- contributing/documentation/index.rst | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/contributing/documentation/index.rst b/contributing/documentation/index.rst index 7c6e4f67f79..dbbfa48b0a4 100644 --- a/contributing/documentation/index.rst +++ b/contributing/documentation/index.rst @@ -9,21 +9,22 @@ More than 1,000 developers all around the world have contributed to Symfony documentation and we are glad that you are considering joining this big family. This guide will explain everything you need to contribute to the documentation: -* :doc:`The Contribution Process `, +:doc:`The Contribution Process ` explains in detail the steps to follow to contribute fixes and new contents. It follows the standard GitHub contribution process of most Open Source projects, so you may already know everything that is needed. -* :doc:`Formats `, explains the technical - details of the reStructuredText format used to write the docs. Skip it if - you already are familiar with this format. +:doc:`Documentation Formats ` + explains the technical details of the reStructuredText format used to write + the docs. Skip it if you already are familiar with this format. -* :doc:`Standards `, explains how to - write docs and code examples to match the style and tone of the rest of the - documentation. +:doc:`Documentation Standards ` + explains how to write docs and code examples to match the style and tone of + the rest of the documentation. -* :doc:`License `, explains the details of - the Creative Commons BB-SA 3.0 license used by Symfony Documentation. +:doc:`License ` + explains the details of the Creative Commons BB-SA 3.0 license used by the + Symfony Documentation. .. toctree:: :hidden: From f7078dc79b4508786495af07f82c70c54b95f19d Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 4 May 2017 13:22:27 +0200 Subject: [PATCH 3/6] Minor rewords --- contributing/documentation/index.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/contributing/documentation/index.rst b/contributing/documentation/index.rst index dbbfa48b0a4..94df9350e74 100644 --- a/contributing/documentation/index.rst +++ b/contributing/documentation/index.rst @@ -5,25 +5,25 @@ Documentation is as important as code for Open Source projects. That's why 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 all around the world have contributed to Symfony -documentation and we are glad that you are considering joining this big family. -This guide will explain everything you need to contribute to the documentation: +More than 1,000 developers have contributed to Symfony documentation and we are +glad that you are considering joining this big family. This guide will explain +everything you need to contribute to the documentation: :doc:`The Contribution Process ` - explains in detail the steps to follow to contribute fixes and new contents. - It follows the standard GitHub contribution process of most Open Source - projects, so you may already know everything that is needed. + 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 + may already know everything that is needed. :doc:`Documentation Formats ` - explains the technical details of the reStructuredText format used to write + Explains the technical details of the reStructuredText format used to write the docs. Skip it if you already are familiar with this format. :doc:`Documentation Standards ` - explains how to write docs and code examples to match the style and tone of + Explains how to write docs and code examples to match the style and tone of the rest of the documentation. :doc:`License ` - explains the details of the Creative Commons BB-SA 3.0 license used by the + Explains the details of the Creative Commons BB-SA 3.0 license used by the Symfony Documentation. .. toctree:: From 008db1069aaad850aaa857b93bdc8e4faad4d259 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sun, 7 May 2017 19:33:22 +0200 Subject: [PATCH 4/6] Fixes, rewords and simplifications --- contributing/documentation/index.rst | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/contributing/documentation/index.rst b/contributing/documentation/index.rst index 94df9350e74..015d6141915 100644 --- a/contributing/documentation/index.rst +++ b/contributing/documentation/index.rst @@ -1,29 +1,27 @@ Contributing Documentation ========================== -Documentation is as important as code for Open Source projects. That's why -Symfony dedicates a great amount of resources to document new features and to -keep the rest of the documentation up-to-date. +Documentation is as important as code. That's why 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 -glad that you are considering joining this big family. This guide will explain -everything you need to contribute to the documentation: +These short guides explain everything you need to contribute to the documentation: :doc:`The Contribution Process ` - 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 - may already know everything that is needed. + 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 used to write - the docs. Skip it if you already are familiar with this format. + 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 documentation. + the rest of the existing documentation. :doc:`License ` - Explains the details of the Creative Commons BB-SA 3.0 license used by the + Explains the details of the Creative Commons BY-SA 3.0 license used for the Symfony Documentation. .. toctree:: From 56e51bb70f58ef51c5e87899687a0c7394f58b60 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 9 May 2017 15:22:52 +0200 Subject: [PATCH 5/6] Simplified the intro again --- contributing/documentation/index.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/contributing/documentation/index.rst b/contributing/documentation/index.rst index 015d6141915..769768311dd 100644 --- a/contributing/documentation/index.rst +++ b/contributing/documentation/index.rst @@ -1,11 +1,8 @@ Contributing Documentation ========================== -Documentation is as important as code. That's why Symfony dedicates a great -amount of resources to document new features and to keep the rest of the -documentation up-to-date. - -These short guides explain everything you need to contribute to the documentation: +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 From 8fd37dbcd025043a6b1268da3294f667863feeba Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 9 May 2017 15:54:18 +0200 Subject: [PATCH 6/6] Minor typo --- contributing/documentation/standards.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing/documentation/standards.rst b/contributing/documentation/standards.rst index 77cea866ad5..ec65cc08538 100644 --- a/contributing/documentation/standards.rst +++ b/contributing/documentation/standards.rst @@ -2,7 +2,7 @@ Documentation Standards ======================= Contributions must follow these standards to match the style and tone of the -rest of the Symfony Documentation. +rest of the Symfony documentation. Sphinx ------