Edit contributing guidelines

Add links to the README
Simplify building the manual
Update class reference writing guidelines based on review notes. Re-add lost changes in rebase.
Address review comments in documentation guidelines

README.md

@@ -25,8 +25,9 @@ Here are some quick links to the areas you might be interested in:
 
 1. [Contributing to the online manual](https://docs.godotengine.org/en/latest/community/contributing/documentation_guidelines.html)
 2. [Contributing to the class reference](https://docs.godotengine.org/en/latest/community/contributing/updating_the_class_reference.html)
-3. [Writing guidelines](https://docs.godotengine.org/en/latest/community/contributing/docs_writing_guidelines.html)
-4. [Translating the documentation](https://docs.godotengine.org/en/latest/community/contributing/editor_and_docs_localization.html)
+3. [Content guidelines](https://docs.godotengine.org/en/latest/community/contributing/content_guidelines.html)
+4. [Writing guidelines](https://docs.godotengine.org/en/latest/community/contributing/docs_writing_guidelines.html)
+5. [Translating the documentation](https://docs.godotengine.org/en/latest/community/contributing/editor_and_docs_localization.html)
     
 ## License
 

community/contributing/building_the_manual.rst

@@ -7,20 +7,24 @@ This page explains how to build a local copy of the Godot manual using the
 Sphinx docs engine. This allows you to have local HTML files and build the
 documentation as a PDF, EPUB, or LaTeX file, for example.
 
-To get started, you need to install:
+To get started, you need to:
 
-1. `Sphinx <https://www.sphinx-doc.org/>`__
-2. To build the docs as HTML files, the `readthedocs.org theme
-   <https://github.com/snide/sphinx_rtd_theme>`__
-3. The Sphinx extensions defined in this repository's ``requirements.txt`` file
+1. Clone the `godot-docs repository <https://github.com/godotengine/godot-docs/>`__.
+2. Install `Sphinx <https://www.sphinx-doc.org/>`__
+3. To build the docs as HTML files, install the `readthedocs.org theme
+   <https://github.com/snide/sphinx_rtd_theme>`__.
+4. Install the Sphinx extensions defined in the `godot-docs repository
+   <https://github.com/godotengine/godot-docs/>`__ ``requirements.txt`` file.
 
 We recommend using `pip <https://pip.pypa.io>` _, Python’s package manager to
 install all these tools. It comes pre-installed with `Python
-<https://www.python.org/>`__. Ensure that you install and use Python 3.
+<https://www.python.org/>`__. Ensure that you install and use Python 3. Here are
+the commands to clone the repository and then install all requirements.
 
 .. code:: sh
 
-   pip install -r requirements.txt
+    git clone https://github.com/godotengine/godot-docs.git
+    pip install -r requirements.txt
 
 .. note:: On Linux distributions, you may need to write ``pip3`` instead of
           ``pip`` because you generally have both Python 2 and 3 installed on
@@ -32,13 +36,17 @@ folder of this repository with the following command:
 
 .. code:: sh
 
-   make html
+    # On Linux and MacOS
+    make html
+
+    # On Windows, you need to execute the ``make.bat`` file instead.
+    make.bat html
 
 If you run into errors, you may try the following command:
 
 .. code:: sh
 
-   make SPHINXBUILD=~/.local/bin/sphinx-build html
+    make SPHINXBUILD=~/.local/bin/sphinx-build html
 
 Building the documentation requires at least 8 GB of RAM to run without disk
 swapping, which slows it down. If you have at least 16 GB of RAM, you can speed
@@ -46,11 +54,11 @@ up compilation by running:
 
 .. code:: sh
 
-   # On Linux/macOS
-   make html SPHINXOPTS=-j2
+    # On Linux/macOS
+    make html SPHINXOPTS=-j2
 
-   # On Windows
-   set SPHINXOPTS=-j2 && make html
+    # On Windows
+    set SPHINXOPTS=-j2 && make html
 
 The compilation will take some time as the ``classes/`` folder contains hundreds
 of files.
@@ -68,23 +76,6 @@ from the final HTML documentation but will keep the rest intact.
           <https://github.com/godotengine/godot-docs/issues/3157>`__ for more
           detail.
 
-
-Building with Sphinx on Windows
--------------------------------
-
-On Windows, you need to:
-
-1. Download the Python installer `here <https://www.python.org/downloads/>`__.
-2. Install Python. Be sure to check the “Add Python to PATH” checkbox.
-3. Use the above ``pip`` commands to install required programs.
-
-To build the documentation, open the root directory of this repository in your
-command line and execute ``make.bat`` like so:
-
-.. code:: sh
-
-   make.bat html
-
 Alternatively, you can build the documentation by running the sphinx-build
 program manually:
 
@@ -92,10 +83,6 @@ program manually:
 
    sphinx-build -b html ./ _build
 
-Note that during the first build, various installation prompts may appear and
-ask to install LaTeX plugins. Make sure you don’t miss them, especially if they
-open behind other windows. The build may hang until you confirm these prompts.
-
 Building with Sphinx and virtualenv
 -----------------------------------
 

community/contributing/class_reference_writing_guidelines.rst

@@ -16,34 +16,45 @@ The reference for each class is contained in an XML file like the one below:
 
 .. code-block:: xml
 
-    <class name="Node2D" inherits="CanvasItem" category="Core">
+    <class name="Node2D" inherits="CanvasItem" version="4.0">
         <brief_description>
-            Base node for 2D system.
+            A 2D game object, inherited by all 2D-related nodes. Has a position, rotation, scale, and Z index.
         </brief_description>
         <description>
-            Base node for 2D system. Node2D contains a position, rotation and scale, which is used to position and animate. It can alternatively be used with a custom 2D transform ([Matrix32]). A tree of Node2Ds allows complex hierarchies for animation and positioning.
+            A 2D game object, with a transform (position, rotation, and scale). All 2D nodes, including physics objects and sprites, inherit from Node2D. Use Node2D as a parent node to move, scale and rotate children in a 2D project. Also gives control of the node's render order.
         </description>
+        <tutorials>
+            <link title="Custom drawing in 2D">https://docs.godotengine.org/en/latest/tutorials/2d/custom_drawing_in_2d.html</link>
+            <link title="All 2D Demos">https://github.com/godotengine/godot-demo-projects/tree/master/2d</link>
+        </tutorials>
         <methods>
-            <method name="set_pos">
-                <argument index="0" name="pos" type="Vector2">
+            <method name="apply_scale">
+                <return type="void">
+                </return>
+                <argument index="0" name="ratio" type="Vector2">
                 </argument>
                 <description>
-                    Sets the position of the 2D node.
+                    Multiplies the current scale by the [code]ratio[/code] vector.
                 </description>
             </method>
             [...]
-            <method name="edit_set_pivot">
-                <argument index="0" name="arg0" type="Vector2">
+            <method name="translate">
+                <return type="void">
+                </return>
+                <argument index="0" name="offset" type="Vector2">
                 </argument>
                 <description>
+                    Translates the node by the given [code]offset[/code] in local coordinates.
                 </description>
             </method>
         </methods>
         <members>
-            <member name="global_position" type="Vector2" setter="set_global_position" getter="get_global_position" brief="">
+            <member name="global_position" type="Vector2" setter="set_global_position" getter="get_global_position">
+                Global position.
             </member>
             [...]
-            <member name="z_as_relative" type="bool" setter="set_z_as_relative" getter="is_z_relative" brief="">
+            <member name="z_index" type="int" setter="set_z_index" getter="get_z_index" default="0">
+                Z index. Controls the order in which the nodes render. A node with a higher Z index will display in front of others.
             </member>
         </members>
         <constants>
@@ -54,15 +65,16 @@ The reference for each class is contained in an XML file like the one below:
 It starts with brief and long descriptions. In the generated docs, the brief
 description is always at the top of the page, while the long description lies
 below the list of methods, variables, and constants. You can find methods,
-member variables, constants, and signals in separate XML nodes. For each, learn
-how they work in Godot's source code, and fill their <description> tag.
+member variables, constants, and signals in separate XML nodes.
 
-Our job is to complete or improve the text in these tags:
+For each, you want to learn how they work in Godot's source code. Then, fill
+their documentation by completing or improving the text in these tags:
 
 - `<brief_description>`
 - `<description>`
 - `<constant>`
-- `<method>` (in its `<description>` tag; return types and arguments don't take separate documentation strings)
+- `<method>` (in its `<description>` tag; return types and arguments don't take separate
+  documentation strings)
 - `<member>`
 - `<signal>` (in its `<description>` tag; arguments don't take separate documentation strings)
 - `<constant>`
@@ -72,6 +84,8 @@ Write in a clear and simple language. Always follow the :ref:`writing guidelines
 **Do not leave empty lines** in the descriptions: each line in the XML file will
 result in a new paragraph, even if it is empty.
 
+.. _doc_class_reference_writing_guidelines_editing_xml:
+
 How to edit class XML
 ---------------------
 
@@ -80,20 +94,27 @@ reference. The folder contains an XML file for each class. The XML lists the
 constants and methods you will find in the class reference. Godot generates and
 updates the XML automatically.
 
+.. note:: For some modules in the engine's source code, you'll find the XML
+          files in the ``modules/<module_name>/doc_classes/`` directory instead.
+
 Edit it using your favorite text editor. If you use a code editor, make sure
-that it doesn't change the indent style: you should use tabs for the XML, and
+that it doesn't change the indent style: you should use tabs for the XML and
 four spaces inside BBCode-style blocks. More on that below.
 
-To check that the modifications you've made are correct in the
-generated documentation, you need to build Godot. To learn how, read the
-:ref:`compilation guide <toc-devel-compiling>`. Then, run the editor and open
-the help for the page you modified.
+To check that the modifications you've made are correct in the generated
+documentation, navigate to the ``doc/`` folder and run the command ``make rst``.
+This will convert the XML files to the online documentation's format and output
+errors if anything's wrong.
+
+Alternatively, you can build Godot and open the modified page in the built-in
+code reference. To learn how to compile the engine, read the :ref:`compilation
+guide <toc-devel-compiling>`.
 
 We recommend using a code editor that supports XML files like Vim, Atom, Code,
 Notepad++, or another to comfortably edit the file. You can also use their
 search feature to find classes and properties quickly.
 
-.. _doc_updating_the_class_reference_bbcode:
+.. _doc_class_reference_writing_guidelines_bbcode:
 
 Improve formatting with BBCode style tags
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -101,33 +122,39 @@ Improve formatting with BBCode style tags
 Godot's class reference supports BBCode-like tags. They add nice formatting to
 the text. Here's the list of available tags:
 
-+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+
-| Tag                       | Effect                         | Usage                             | Result                                            |
-+===========================+================================+===================================+===================================================+
-| [Class]                   | Link a class                   | Move the [Sprite].                | Move the :ref:`class_sprite`.                     |
-+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+
-| [method methodname]       | Link to a method in this class | Call [method hide].               | See :ref:`hide <class_spatial_method_hide>`.      |
-+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+
-| [method Class.methodname] | Link to another class's method | Call [method Spatial.hide].       | See :ref:`hide <class_spatial_method_hide>`.      |
-+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+
-| [member membername]       | Link to a member in this class | Get [member scale].               | Get :ref:`scale <class_node2d_property_scale>`.   |
-+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+
-| [member Class.membername] | Link to another class's member | Get [member Node2D.scale].        | Get :ref:`scale <class_node2d_property_scale>`.   |
-+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+
-| [signal signalname]       | Link to a signal in this class | Emit [signal renamed].            | Emit :ref:`renamed <class_node_signal_renamed>`.  |
-+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+
-| [signal Class.signalname] | Link to another class's signal | Emit [signal Node.renamed].       | Emit :ref:`renamed <class_node_signal_renamed>`.  |
-+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+
-| [b] [/b]                  | Bold                           | Some [b]bold[/b] text.            | Some **bold** text.                               |
-+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+
-| [i] [/i]                  | Italic                         | Some [i]italic[/i] text.          | Some *italic* text.                               |
-+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+
-| [code] [/code]            | Monospace                      | Some [code]monospace[/code] text. | Some ``monospace`` text.                          |
-+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+
-| [kbd] [/kbd]              | Keyboard/mouse shortcut        | Some [kbd]Ctrl + C[/kbd] key.     | Some :kbd:`Ctrl + C` key.                         |
-+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+
-| [codeblock] [/codeblock]  | Multiline preformatted block   | *See below.*                      | *See below.*                                      |
-+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| Tag                        | Effect                               | Usage                             | Result                                            |
++============================+======================================+===================================+===================================================+
+| [Class]                    | Link a class                         | Move the [Sprite].                | Move the :ref:`class_sprite`.                     |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [method methodname]        | Link to a method in this class       | Call [method hide].               | See :ref:`hide <class_spatial_method_hide>`.      |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [method Class.methodname]  | Link to another class's method       | Call [method Spatial.hide].       | See :ref:`hide <class_spatial_method_hide>`.      |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [member membername]        | Link to a member in this class       | Get [member scale].               | Get :ref:`scale <class_node2d_property_scale>`.   |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [member Class.membername]  | Link to another class's member       | Get [member Node2D.scale].        | Get :ref:`scale <class_node2d_property_scale>`.   |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [signal signalname]        | Link to a signal in this class       | Emit [signal renamed].            | Emit :ref:`renamed <class_node_signal_renamed>`.  |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [signal Class.signalname]  | Link to another class's signal       | Emit [signal Node.renamed].       | Emit :ref:`renamed <class_node_signal_renamed>`.  |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [b] [/b]                   | Bold                                 | Some [b]bold[/b] text.            | Some **bold** text.                               |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [i] [/i]                   | Italic                               | Some [i]italic[/i] text.          | Some *italic* text.                               |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [code] [/code]             | Monospace                            | Some [code]monospace[/code] text. | Some ``monospace`` text.                          |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [kbd] [/kbd]               | Keyboard/mouse shortcut              | Some [kbd]Ctrl + C[/kbd] key.     | Some :kbd:`Ctrl + C` key.                         |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [codeblock] [/codeblock]   | Multiline preformatted block         | *See below.*                      | *See below.*                                      |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [codeblocks] [/codeblocks] | [codeblock] for multiple languages   | *See below.*                      | *See below.*                                      |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [gdscript] [/gdscript]     | GDScript codeblock tab in codeblocks | *See below.*                      | *See below.*                                      |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [csharp] [/csharp]         | C# codeblock tab in codeblocks       | *See below.*                      | *See below.*                                      |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
 
 Use ``[codeblock]`` for pre-formatted code blocks. Inside ``[codeblock]``,
 always use **four spaces** for indentation. The parser will delete tabs. For
@@ -135,14 +162,61 @@ example:
 
 .. code-block:: none
 
-    [codeblock] func _ready(): var sprite = get_node("Sprite")
-    print(sprite.get_pos()) [/codeblock]
+    [codeblock]
+    func _ready():
+        var sprite = get_node("Sprite")
+        print(sprite.get_pos())
+    [/codeblock]
 
 Will display as:
 
 .. code-block:: gdscript
 
-    func _ready(): var sprite = get_node("Sprite") print(sprite.get_pos())
+    func _ready():
+        var sprite = get_node("Sprite")
+        print(sprite.get_pos())
+
+If you need to have different code version in GDScript and C#, use
+``[codeblocks]`` instead. If you use ``[codeblocks]``, you also need to have at
+least one of the language-specific tags, ``[gdscript]`` and ``[csharp]``.
+
+Always write GDScript code examples first! You can use this `experimental code
+translation tool <https://github.com/HaSa1002/codetranslator>`_ to speed up your
+workflow.
+
+.. code-block:: none
+
+    [codeblocks]
+    [gdscript]
+    func _ready():
+        var sprite = get_node("Sprite")
+        print(sprite.get_pos())
+    [/gdscript]
+    [csharp]
+    public override void _Ready()
+    {
+        var sprite = GetNode("Sprite");
+        GD.Print(sprite.GetPos());
+    }
+    [/csharp]
+    [/codeblocks]
+
+The above will display as:
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    func _ready():
+        var sprite = get_node("Sprite")
+        print(sprite.get_pos())
+
+ .. code-tab:: csharp
+
+    public override void _Ready()
+    {
+        var sprite = GetNode("Sprite");
+        GD.Print(sprite.GetPos());
+    }
 
 To denote important information, add a paragraph starting with "[b]Note:[/b]" at
 the end of the description:
@@ -157,16 +231,14 @@ the end of the description:
 
 .. code-block:: none
 
-    [b]Warning:[/b] If this property is set to [code]true[/code], it allows
-    clients to execute arbitrary code on the server.
+    [b]Warning:[/b] If this property is set to [code]true[/code], it allows clients to execute arbitrary code on the server.
 
 For deprecated properties, add a paragraph starting with "[i]Deprecated.[/i]".
 Notice the use of italics instead of bold:
 
 .. code-block:: none
 
-    [i]Deprecated.[/i] This property has been replaced by [member
-    other_property].
+    [i]Deprecated.[/i] This property has been replaced by [member other_property].
 
 In all the paragraphs described above, make sure the punctuation is part of the
 BBCode tags for consistency.

community/contributing/documentation_guidelines.rst

@@ -49,7 +49,7 @@ contribute, you should also read:
 Contributing changes
 --------------------
 
-**Pull Requests should use the ``master`` branch by default**. Only make Pull
+**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.
 
@@ -69,6 +69,9 @@ See `Contribute to the Class Reference
 <https://docs.godotengine.org/en/latest/community/contributing/updating_the_class_reference.html>`__
 for details.
 
+.. seealso:: To build the manual and test changes on your computer, see
+             :ref:`doc_building_the_manual`
+
 Editing pages online
 --------------------
 
@@ -100,19 +103,20 @@ they're good. They may also make changes or ask you to do so before merging.
 Adding new pages
 ----------------
 
+Before adding a new page, please ensure that it fits in the documentation:
+
+1. Look for `existing issues
+   <https://github.com/godotengine/godot-docs/issues>`_ or open a new one to see
+   if the page is necessary.
+2. Ensure there isn't a page that already covers the topic.
+3. Read our :ref:`doc_content_guidelines`.
+
 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:``).
+want to add a file to, e.g. ``tutorials/3d/light_baking.rst``.
 
 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``.
+e.g. ``tutorials/3d/index.rst``). Add your new filename to the list on a new
+line, using a relative path and no extension, e.g. here ``light_baking``.
 
 Titles
 ~~~~~~
@@ -126,6 +130,8 @@ Always begin pages with their title and a Sphinx reference name:
     Insert your title here
     ======================
 
+The reference ``_doc_insert_your_title_here`` and the title should match.
+
 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).
@@ -148,8 +154,10 @@ 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.
+<https://www.sphinx-doc.org/en/stable/index.html>`__ for more details. To learn
+how to use Sphinx directives like ``.. note::`` or ``.. seealso::``, check out
+the `Sphinx directives documentation
+<https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html>`__.
 
 Adding images and attachments
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

community/contributing/editor_and_docs_localization.rst

@@ -324,7 +324,7 @@ breaks if they are not part of the original translation.
 .. seealso::
 
     See our documentation for class reference writers for the :ref:`list of
-    BBCode-like tags <doc_updating_the_class_reference_bbcode>` which are used
+    BBCode-like tags <doc_class_reference_writing_guidelines_bbcode>` which are used
     throughout the class reference.
 
 Offline translation and testing

community/contributing/index.rst

@@ -38,6 +38,7 @@ Writing documentation
    :name: toc-community-contributing-to-documentation
 
    documentation_guidelines
+   content_guidelines
    docs_writing_guidelines
    updating_the_class_reference
    class_reference_writing_guidelines

community/contributing/updating_the_class_reference.rst

@@ -41,6 +41,9 @@ You can find the source files for the class reference in Godot's GitHub
 repository: `doc/classes/
 <https://github.com/godotengine/godot/tree/master/doc/classes>`_.
 
+.. note:: For some modules in the engine's source code, you'll find the XML
+          files in the ``modules/<module_name>/doc_classes/`` directory instead.
+
 There are five steps to update the class reference:
 
 1. Fork `Godot's repository <https://github.com/godotengine/godot>`_
@@ -103,7 +106,7 @@ Keeping your local clone up-to-date
 
 Other writers contribute to Godot's documentation. Your local repository will
 fall behind it. You will have to synchronize it, especially if other
-contributors update the class reference while working on it.
+contributors update the class reference while you are working on it.
 
 First, add an ``upstream`` Git *remote*. Remotes are links to online repositories
 from which you can download new files. The following command registers a new
@@ -113,27 +116,6 @@ remote named "upstream" that links to the original Godot repository.
 
     git remote add upstream https://github.com/godotengine/godot
 
-You can check the list of all remote servers with this command:
-
-::
-
-    git remote -v
-
-You should have two remotes:
-
-1. ``origin``, corresponding to your fork on GitHub. Git adds it by default when
-   you clone a repository.
-2. ``upstream``, that you just added.
-
-The output should look like the following:
-
-::
-
-    origin https://github.com/your_name/godot.git (fetch) origin
-    https://github.com/your_name/godot.git (push) upstream
-    https://github.com/godotengine/godot.git (fetch) upstream
-    https://github.com/godotengine/godot.git (push)
-
 Each time you want to synchronize your branch with the upstream repository,
 enter:
 
@@ -161,13 +143,19 @@ branch with the Godot repository, and create a new branch:
 
 ::
 
-    git checkout master git branch -d your-new-branch-name git pull --rebase
-    upstream master git checkout -b your-new-branch-name
+    git checkout master
+    git pull --rebase upstream master
+    # Creates a new branch and checks out to it
+    git checkout -b your-new-branch-name
 
 If you're feeling lost by now, come to our `IRC channels
 <https://webchat.freenode.net/?channels=#godotengine>`_ and ask for help.
 Experienced Git users will give you a hand.
 
+Alternatively, you can join the `Godot Discord server
+<https://discord.gg/4JBkykG>`_ and participate in the ``#documentation``
+channel.
+
 Submitting your changes
 ~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -188,33 +176,29 @@ in the GitHub documentation.
 
 .. warning::
 
-    You should avoid editing files directly on GitHub in the godot engine
-    repository. As hundreds of contributors work on the engine, the Git history
-    must stay clean. Each commit should bundle all related improvements you make
-    to the class reference.
+    Unless you make minor changes, like fixing a typo, we do not recommend using the GitHub web editor to edit the class reference's XML.
 
-    Editing from GitHub creates a new branch and Pull Request every time you
-    save your changes. Suppose days pass before your changes get a review. In
-    that case, you won't be able to update to the latest version of the
-    repository cleanly. Also, it's harder to keep clean indents with GitHub's
-    text editor. And they're essential in the class reference.
+    It lacks features to edit XML well, like keeping indentations consistent, and it does not allow amending commits based on reviews.
+
+    Also, it doesn't allow you to test your changes in the engine or with validation
+    scripts as described in
+    :ref:`doc_class_reference_writing_guidelines_editing_xml`.
 
 Updating the documentation template
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-When classes are modified in the source code, the documentation template might become outdated. To make sure that you are editing an up-to-date version, you first need to compile Godot (you can follow the :ref:`doc_introduction_to_the_buildsystem` page), and then run the following command (assuming 64-bit Linux):
-
-::
-
-    ./bin/godot.linuxbsd.tools.64 --doctool .
+When you create a new class or modify the engine's API, you need to re-generate the XML files in ``doc/classes/``.
 
-The XML files in doc/classes should then be up-to-date with current Godot Engine features. You can then check what changed using the ``git diff`` command. If there are changes to other classes than the one you are planning to document, please commit those changes first before starting to edit the template:
+To do so, you first need to compile Godot. See the
+:ref:`doc_introduction_to_the_buildsystem` page to learn how. Then, execute the
+compiled godot executable with the ``--doctool`` option. If you're on 64-bit
+Linux, the command is:
 
 ::
 
-    git add doc/classes/*.xml
-    git commit -m "Sync classes reference template with current code base"
-
-You are now ready to edit this file to add stuff.
+    ./bin/godot.linuxbsd.tools.64 --doctool .
 
-**Note:** If this has been done recently by another contributor, you don't forcefully need to go through these steps (unless you know that the class you plan to edit *has* been modified recently).
+The XML files in doc/classes should then be up-to-date with current Godot Engine
+features. You can then check what changed using the ``git diff`` command. Please
+only include changes that are relevant to your work on the API in your commits.
+You can discard changes in other XML files using ``git checkout``.