Reorder and edit the documentation guidelines

community/contributing/documentation_guidelines.rst

@@ -4,7 +4,7 @@ Contributing to the documentation
 =================================
 
 This guide explains how to contribute to Godot's documentation, be it by
-writing, reviewing, or translating pages.
+writing or reviewing pages.
 
 .. seealso::
 
@@ -19,19 +19,56 @@ files in the `godot-docs GitHub repository
 <https://github.com/godotengine/godot-docs>`_. Modifying those pages in a pull
 request and triggers a rebuild of the online documentation upon merging.
 
-
-
 .. seealso:: For details on Git usage and the pull request workflow, please
              refer to the :ref:`doc_pr_workflow` page. Most of what it describes
              regarding the main godotengine/godot repository is also valid for
              the docs repository.
 
-.. warning:: The class reference's source files are in the `Godot engine repository
-             <https://github.com/godotengine/godot>`_. We generate the :ref:`Godot API
-             <toc-class-ref>` section of this documentation from them. If you want to update the
-             description of a class, its methods, or properties, read
+.. warning:: The class reference's source files are in the `Godot engine
+             repository <https://github.com/godotengine/godot>`_. We generate
+             the :ref:`Godot API <toc-class-ref>` section of this documentation
+             from them. If you want to update the description of a class, its
+             methods, or properties, read
              :ref:`doc_updating_the_class_reference`.
 
+What is the Godot documentation
+-------------------------------
+
+The Godot documentation is intended as a comprehensive reference manual for the
+Godot game engine. It is not meant to contain step-by-step tutorials, except for
+two game creation tutorials in the Getting Started section.
+
+We strive to write factual content in an accessible and well-written English. To
+contribute, you should also read:
+
+1. The :ref:`doc_docs_writing_guidelines`. There, you will find rules and
+   recommendations to write in a way that everyone understands.
+2. The content guidelines. They explain the principles we follow to write the
+   documentation and the kind of content we accept.
+
+Contributing changes
+--------------------
+
+**Pull Requests should use the ``master`` branch by default**. Only make Pull
+ Requests against other branches (e.g. ``2.1`` or ``3.0``) if your changes only
+ apply to that specific version of Godot.
+
+Though less convenient to edit than a wiki, this Git repository is where we
+write the documentation. Having direct access to the source files in a revision
+control system is a plus to ensure our documentation quality.
+
+Editing existing pages
+~~~~~~~~~~~~~~~~~~~~~~
+
+To edit an existing page, locate its .rst source file and open it in your
+favorite text editor. You can then commit the changes, push them to your fork,
+and make a pull request. **Note that the pages in ``classes/`` should not be
+edited here. They are automatically generated from Godot’s**\ `XML class
+references <https://github.com/godotengine/godot/tree/master/doc/classes>`__\
+**.** See `Contribute to the Class Reference
+<https://docs.godotengine.org/en/latest/community/contributing/updating_the_class_reference.html>`__
+for details.
+
 Editing pages online
 --------------------
 
@@ -59,140 +96,86 @@ and to log in to use it. Once logged in, you can propose change like so:
 Another contributor will review your changes and merge them into the docs if
 they're good. They may also make changes or ask you to do so before merging.
 
-Contributing changes
---------------------
+Adding new pages
+----------------
+
+To add a new page, create a .rst file with a meaningful name in the section you
+want to add a file to, e.g. \ ``tutorials/3d/light_baking.rst``. Write its
+content like you would do for any other file, and make sure to define a
+reference name for Sphinx at the beginning of the file (check other files for
+the syntax), based on the file name with a “doc\_” prefix (e.g. ``..
+_doc_light_baking:``).
+
+You should then add your page to the relevant “toctree” (table of contents,
+e.g. \ ``tutorials/3d/index.rst``). By convention, the files used to define the
+various levels of toctree are prefixed with an underscore, so in the above
+example the file should be referenced in ``tutorials/3d/_3d_graphics.rst``. Add
+your new filename to the list on a new line, using a relative path and no
+extension, e.g. here ``light_baking``.
 
-**Pull Requests should use the ``master`` branch by default. Only make
-Pull Requests against other branches (e.g. ``2.1`` or ``3.0``) if your
-changes only apply to that specific version of Godot.**
+Titles
+~~~~~~
 
-Though arguably less convenient to edit than a wiki, this Git repository
-is meant to receive pull requests to always improve the documentation,
-add new pages, etc. Having direct access to the source files in a
-revision control system is a big plus to ensure the quality of our
-documentation.
+Always begin pages with their title and a Sphinx reference name:
 
-Editing existing pages
-~~~~~~~~~~~~~~~~~~~~~~
+::
 
-To edit an existing page, locate its .rst source file and open it in
-your favorite text editor. You can then commit the changes, push them to
-your fork and make a pull request. **Note that the pages in ``classes/``
-should not be edited here, they are automatically generated from
-Godot’s**\ `XML class
-references <https://github.com/godotengine/godot/tree/master/doc/classes>`__\ **.**
-See `Contribute to the Class
-Reference <https://docs.godotengine.org/en/latest/community/contributing/updating_the_class_reference.html>`__
-for details.
+    .. _doc_insert_your_title_here:
 
-Adding new pages
-~~~~~~~~~~~~~~~~
-
-To add a new page, create a .rst file with a meaningful name in the
-section you want to add a file to,
-e.g. \ ``tutorials/3d/light_baking.rst``. Write its content like you
-would do for any other file, and make sure to define a reference name
-for Sphinx at the beginning of the file (check other files for the
-syntax), based on the file name with a “doc\_” prefix
-(e.g. ``.. _doc_light_baking:``).
-
-You should then add your page to the relevant “toctree” (table of
-contents, e.g. \ ``tutorials/3d/index.rst``). By convention, the files
-used to define the various levels of toctree are prefixed with an
-underscore, so in the above example the file should be referenced in
-``tutorials/3d/_3d_graphics.rst``. Add your new filename to the list on
-a new line, using a relative path and no extension, e.g. here
-``light_baking``.
+    Insert your title here
+    ======================
+
+The reference allows linking to this page using the ``:ref:`` format, e.g.
+``:ref:`doc_insert_your_title_here``` would link to the above example page (note
+the lack of leading underscore in the reference).
+
+Write your titles like plain sentences, without capitalizing each word:
+
+-  **Good**: Understanding signals in Godot
+-  **Bad**: Understanding Signals In Godot
+
+Only propers nouns, projects, people, and node class names should have their
+first letter capitalized.
 
 Sphinx and reStructuredText syntax
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Check Sphinx’s `reST
-Primer <https://www.sphinx-doc.org/en/stable/rest.html>`__ and the
-`official reference <http://docutils.sourceforge.net/rst.html>`__ for
+Check Sphinx’s `reST Primer <https://www.sphinx-doc.org/en/stable/rest.html>`__
+and the `official reference <http://docutils.sourceforge.net/rst.html>`__ for
 details on the syntax.
 
-Sphinx uses specific reST comments to do specific operations, like
-defining the table of contents (``:toctree:``) or cross-referencing
-pages. Check the `official Sphinx
-documentation <https://www.sphinx-doc.org/en/stable/index.html>`__ for
-more details, or see how things are done in existing pages and adapt it
-to your needs.
+Sphinx uses specific reST comments to do specific operations, like defining the
+table of contents (``:toctree:``) or cross-referencing pages. Check the
+`official Sphinx documentation
+<https://www.sphinx-doc.org/en/stable/index.html>`__ for more details, or see
+how things are done in existing pages and adapt it to your needs.
 
 Adding images and attachments
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To add images, please put them in an ``img/`` folder next to the .rst
-file with a meaningful name and include them in your page with:
+To add images, please put them in an ``img/`` folder next to the .rst file with
+a meaningful name and include them in your page with:
 
 .. code:: rst
 
    .. image:: img/image_name.png
 
-Similarly, you can include attachments (like assets as support material
-for a tutorial) by placing them into a ``files/`` folder next to the
-.rst file, and using this inline markup:
+Similarly, you can include attachments, like assets as support material for a
+tutorial, by placing them into a ``files/`` folder next to the .rst file, and
+using this inline markup:
 
 .. code:: rst
 
    :download:`myfilename.zip <files/myfilename.zip>`
 
-What is the Godot documentation
--------------------------------
-
-The Godot documentation is intended as a comprehensive reference manual for the
-Godot game engine. It is not meant to contain step-by-step tutorials, with the
-exception of two game creation tutorials in the Getting Started section.
-
-We strive to write objective content in accessible and well-written English. To
-contribute, you should also read:
-
-- The :ref:`doc_docs_writing_guidelines`. There, you will find rules to write
-
-- Tutorial: a page aiming at explaining how to use one or more concepts in the
-   editor or scripts in order to achieve a specific goal with a learning purpose
-   (e.g. "Making a simple 2d Pong game", "Applying forces to an object").
-- Documentation: a page describing precisely one and only one concept at a time,
-   if possible exhaustively (e.g. the list of methods of the Sprite class, or an
-   overview of the input management in Godot).
-
-You are free to write the kind of documentation you wish, as long as you respect
-the following rules (and the ones on the repo).
-
-Titles
-------
-
-Always begin pages with their title and a Sphinx reference name:
-
-::
-
-    .. _doc_insert_your_title_here:
-
-    Insert your title here
-    ======================
-
-The reference allows linking to this page using the ``:ref:`` format, e.g.
-``:ref:`doc_insert_your_title_here``` would link to the above example page
-(note the lack of leading underscore in the reference).
-
-Also, avoid American CamelCase titles: title's first word should begin
-with a capitalized letter, and every following word should not. Thus,
-this is a good example:
-
--  Insert your title here
-
-And this is a bad example:
-
--  Insert Your Title Here
-
-Only project, people and node class names should have capitalized first
-letter.
 
 License
 -------
 
 This documentation and every page it contains is published under the terms of
-the `Creative Commons Attribution 3.0 license (CC-BY-3.0) <https://tldrlegal.com/license/creative-commons-attribution-(cc)>`_, with attribution to "Juan Linietsky, Ariel Manzur and the Godot community".
+the `Creative Commons Attribution 3.0 license (CC-BY-3.0)
+<https://tldrlegal.com/license/creative-commons-attribution-(cc)>`_, with
+attribution to "Juan Linietsky, Ariel Manzur and the Godot community".
 
 By contributing to the documentation on the GitHub repository, you agree that
 your changes are distributed under this license.