Proof and rewrite the class ref contribution guide

- edit to better fit the new writing guidelines: Shorten sentences, remove passive voice, etc
- shorten XML example
- add video guide
- detail git workflow
- add a 5 points bullet list to reflect the steps to contribute to the class reference

community/contributing/updating_the_class_reference.rst

@@ -1,160 +1,128 @@
 .. _doc_updating_the_class_reference:
 
-Updating the class reference
-============================
+Contribute to the Class Reference
+=================================
 
-Godot Engine provides an extensive panel of nodes and singletons that you can
-use with GDScript to develop your games. All those classes are listed and
-documented in the :ref:`class reference <toc-class-ref>`, which is available
-both in the online documentation and offline from within the engine.
+Godot ships with many nodes and singletons to help you develop your games in GDscript. Each is a class, documented in the :ref:`class reference <toc-class-ref>`. This reference is essential for anyone learning the engine: it is available both online and in the engine. 
 
-The class reference is however not 100% complete. Some methods, constants and
-signals have not been described yet, while others may have their implementation
-changed and thus need an update. Updating the class reference is a tedious work
-and the responsibility of the community: if we all partake in the effort, we
-can fill in the blanks and ensure a good documentation level in no time!
+But it's incomplete. Many methods, variables and signals lack descriptions. Others changed with recent releases and need updates. The developers can't write the entire reference on their own. Godot needs you, all of us, to contribute.
 
-**Important notes:**
+**Important:** we use `a collaborative document <https://hackmd.io/s/H1es51Oeqb>`_ to track who's working on what class. Always notify other writers about what you are working on. You'll find the instructions in the doc.
 
--  To coordinate the effort and have an overview of the current status, we use
-   `a collaborative pad <https://etherpad.net/p/godot-classref-status>`_. Please
-   follow the instructions there to notify the other documentation writers about
-   what you are working on.
--  We aim at completely filling the class reference in English
-   first. Once it nears 90-95% completion, we could start thinking about
-   localisating in other languages.
+This guide is available as a `Youtube video <https://www.youtube.com/watch?v=mKKjOulm5XI>`_.
 
-Workflow for updating the class reference
------------------------------------------
 
-The source file of the class reference is an XML file in the main Godot source
-repository on GitHub, `doc/base/classes.xml <https://github.com/godotengine/godot/blob/master/doc/base/classes.xml>`_.
-As of now, it is relatively heavy (more than 1 MB), so it can't be edited online
-using GitHub's text editor.
+How to contribute
+-----------------
 
-The workflow to update the class reference is therefore:
+The class reference lies in the following XML file, in Godot's GitHub repository: `doc/base/classes.xml <https://github.com/godotengine/godot/blob/master/doc/base/classes.xml>`_. As it's over 1MB, you can't edit it online. To update the class reference:
 
--  Fork the `upstream repository <https://github.com/godotengine/godot>`_ and clone
-   your fork.
--  Edit the ``doc/base/classes.xml`` file, commit your changes and push to your
-   fork.
--  Make a pull request on the upstream repository.
+There are 5 steps to update the class reference (full guide below):
 
-The following section details this workflow, and gives also additional information
-about how to synchronise the XML template with the current state of the source code,
-or what should be the formatting of the added text.
+1. Fork `Godot's repository <https://github.com/godotengine/godot>`_ 
+2. Clone your fork on your computer
+3. Edit the ``doc/base/classes.xml`` file to write documentation
+4. Commit your changes and push them to your fork
+5. Make a pull request on the Godot repository
 
-**Important:** The class reference is also :ref:`available in the online documentation <toc-class-ref>`,
-which is hosted alongside the rest of the documentation in the
-`godot-docs <https://github.com/godotengine/godot-docs>`_ git repository. The rST files
-should however **not be edited directly**, they are generated via a script from the
-``doc/base/classes.xml`` file described above.
+**Important:** always use this XML file to edit the API reference. Do not edit the generated .rST files :ref:`in the online documentation <toc-class-ref>`, hosted in the `godot-docs <https://github.com/godotengine/godot-docs>`_ repository.
 
-Getting started with GitHub
----------------------------
+Get started with GitHub
+-----------------------
 
-This section describes step-by-step the typical workflow to fork the git repository,
-or update an existing local clone of your fork, and then prepare a pull request.
+If you're new to git and GitHub, this guide will help you get started. You'll learn to:
 
-Fork Godot Engine
-~~~~~~~~~~~~~~~~~
+- Fork and clone Godot's repository
+- Keep your fork up to date with other contributors
+- Create a pull request so your improvements end in the official docs
 
-First of all, you need to fork the Godot Engine on your own GitHub
-repository.
+If you're brand new to git, the version-control system Godot uses, go through GitHub's interactive guide. You'll learn some essential vocabulary and get a sense for the tool.
+https://try.github.io/levels/1/challenges/1
 
-You will then need to clone the master branch of Godot Engine in order
-to work on the most recent version of the engine, including all of its
-features.
+Fork Godot
+~~~~~~~~~~
+
+Fork the Godot Engine into a GitHub repository of your own.
+
+Clone the repository on your computer:
 
 ::
 
     git clone https://github.com/your_name/godot.git
 
-Then, create a new git branch that will contain your changes.
+Create a new branch to make your changes. It makes it a lot easier to sync your improvements with other docs writers, and it's easier to cleanup your repository clean if you have any issues with git.
 
 ::
 
-    git checkout -b classref-edit
+    git checkout -b your-new-branch-name
 
-The branch you just created is identical to current master branch of
-Godot Engine. It already contains a ``doc/`` folder, with the current
-state of the class reference. Note that you can set whatever name
-you want for the branch, ``classref-edit`` is just an example.
+The new branch is the same as your master branch, until you start to write API docs. In the ``doc/`` folder, you'll find the class reference.
 
-Keeping your local clone up-to-date
+How to keep your local clone up-to-date
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you already have a local clone of your own fork, it might happen
-pretty fast that it will diverge with the upstream git repository.
-For example other contributors might have updated the class reference
-since you last worked on it, or your own commits might have been squashed
-together when merging your pull request, and thus appear as diverging
-from the upstream master branch.
+Other writers contribute to Godot's documentation. Your local repository will fall behind it, and you'll have to synchronize it. Especially if other contributors update the class reference while you work on it.
 
-To keep your local clone up-to-date, you should first add an ``upstream``
-git *remote* to work with:
+First add an ``upstream`` git *remote* to work with. Remotes are links to online repositories you can download new files from.
 
 ::
 
     git remote add upstream https://github.com/godotengine/godot
-    git fetch upstream
 
-You only need to run this once to define this remote. The following steps
-will have to be run each time you want to sync your branch to the state
-of the upstream repo:
+You can check the list of all remote servers with:
+
+::
+
+    git remote -v
+
+You should have 2: ``origin``, your fork on github, that git adds by default, and ``upstream``, that you just added:
+
+
+::
+
+    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 sync your branch to the state of the upstream repository, enter:
 
 ::
 
-    git pull --rebase upstream/master
+    git pull --rebase upstream master
+
+This command will first ``fetch``, or download the latest version of the Godot repository. Then, it will reapply your local changes on top.
 
-This command would reapply your local changes (if any) on top of the current
-state of the upstream branch, thus bringing you up-to-date with your own commits
-on top. In case you have local commits that should be discarded (e.g. if your
-previous pull request had 5 small commits that were all merged into one bigger
-commit in the upstream branch), you need to *reset* your branch:
+If you made changes you don't want to keep in your local branch, use the following commands instead:
 
 ::
 
     git fetch upstream
-    git reset --hard upstream/master
+    git reset --hard upstream master
 
-**Warning:** The above command will reset your branch to the state of the
-``upstream/master`` branch, i.e. it will discard all changes which are
-specific to your local branch. So make sure to run this *before* making new
-changes and not afterwards.
+**Warning:** The above command will reset your branch to the state of the ``upstream master`` branch. It will discard all local changes. Make sure to only run this *before* you make important changes.
 
-Alternatively, you can also keep your own master branch (``origin/master``)
-up-to-date and create new branches when wanting to commit changes to the
-class reference:
+Another option is to delete the branch you're working on, synchronize the master branch with the Godot repository, and create a brand new branch:
 
 ::
 
     git checkout master
-    git branch -d my-previous-doc-branch
-    git pull --rebase upstream/master
-    git checkout -b my-new-doc-branch
+    git branch -d your-new-branch-name
+    git pull --rebase upstream master
+    git checkout -b your-new-branch-name
 
-In case of doubt, ask for help on our IRC channels, we have some git gurus
-there.
+If you're feeling lost by now, come to our `IRC channels <http://webchat.freenode.net/?channels=#godotengine>`_ and ask for help. Experienced git users will give you a hand.
 
 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):
+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.x11.tools.64 -doctool doc/base/classes.xml
 
-The doc/base/classes.xml 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:
+The doc/base/classes.xml 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:
 
 ::
 
@@ -163,9 +131,7 @@ starting to edit the template:
 
 You are now ready to edit this file to add stuff.
 
-**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).
+**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).
 
 Push and request a pull of your changes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -179,23 +145,33 @@ repository:
     git commit -m "Explain your modifications."
     git push
 
-When it's done, you can ask for a Pull Request via the GitHub UI of your
-Godot fork.
+When it's done, you can ask for a Pull Request via the GitHub UI of your Godot fork.
+
+How to edit classes.xml
+-----------------------
+
+Edit the file doc/base/classes.xml to update the class reference. It lists all the classes, constants and methods in the class reference. Godot generates and updates it automatically.
+
+Edit it using your favourite text editor. If you use a code editor, make sure that it doesn't change the indent style. E.g. change all tabs to spaces.
+
+How to write the class reference
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Editing the doc/base/classes.xml file
--------------------------------------
+Each class has a brief and a long description. The brief description is always at the top of the page, while the full description lies below the list of methods, variables and constants. Methods, member variables, constants and signals are in separate categories or XML nodes. For each, learn how they work in Godot's source code, and fill their <description>.
 
-This file is generated and updated by Godot Engine. It is used by the
-editor as base for the Help section.
+Our job is to add the missing text between these marks:
+
+-  <description></description>
+-  <brief_description></brief_description>
+-  <constant></constant>
+-  <member></member>
+-  <signal></signal>
 
-You can edit this file using your favourite text editor. If you use a code
-editor, make sure that it won't needlessly change the indentation behaviour
-(e.g. change all tabs to spaces).
+Write in a clear and simple language. Always follow the :ref:`class_reference_styleguide` to keep your descriptions short and easy to read. **Do not leave empty lines** in the descriptions: each line in the XML file will result in a new paragraph. 
 
-Formatting of the XML file
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+For setters and getters, describe what the setter does in-depth, and only say the minimum in the getter to avoid content duplication. Setters and getters are methods that starts with set\_ or get\_.
 
-Here is an example with the Node2D class:
+Here's how a class looks like in XML:
 
 .. code:: xml
 
@@ -214,88 +190,7 @@ Here is an example with the Node2D class:
                 Set the position of the 2d node.
                 </description>
             </method>
-            <method name="set_rot">
-                <argument index="0" name="rot" type="float">
-                </argument>
-                <description>
-                Set the rotation of the 2d node.
-                </description>
-            </method>
-            <method name="set_scale">
-                <argument index="0" name="scale" type="Vector2">
-                </argument>
-                <description>
-                Set the scale of the 2d node.
-                </description>
-            </method>
-            <method name="get_pos" qualifiers="const">
-                <return type="Vector2">
-                </return>
-                <description>
-                Return the position of the 2D node.
-                </description>
-            </method>
-            <method name="get_rot" qualifiers="const">
-                <return type="float">
-                </return>
-                <description>
-                Return the rotation of the 2D node.
-                </description>
-            </method>
-            <method name="get_scale" qualifiers="const">
-                <return type="Vector2">
-                </return>
-                <description>
-                Return the scale of the 2D node.
-                </description>
-            </method>
-            <method name="rotate">
-                <argument index="0" name="degrees" type="float">
-                </argument>
-                <description>
-            </description>
-            </method>
-            <method name="move_local_x">
-                <argument index="0" name="delta" type="float">
-                </argument>
-                <argument index="1" name="scaled" type="bool" default="false">
-                </argument>
-                <description>
-                </description>
-            </method>
-            <method name="move_local_y">
-                <argument index="0" name="delta" type="float">
-                </argument>
-                <argument index="1" name="scaled" type="bool" default="false">
-                </argument>
-                <description>
-                </description>
-            </method>
-            <method name="get_global_pos" qualifiers="const">
-                <return type="Vector2">
-                </return>
-                <description>
-                Return the global position of the 2D node.
-                </description>
-            </method>
-            <method name="set_global_pos">
-                <argument index="0" name="arg0" type="Vector2">
-                </argument>
-                <description>
-                </description>
-            </method>
-            <method name="set_transform">
-                <argument index="0" name="xform" type="Matrix32">
-                </argument>
-                <description>
-                </description>
-            </method>
-            <method name="set_global_transform">
-                <argument index="0" name="xform" type="Matrix32">
-                </argument>
-                <description>
-                </description>
-            </method>
+            [...]
             <method name="edit_set_pivot">
                 <argument index="0" name="arg0" type="Vector2">
                 </argument>
@@ -303,64 +198,34 @@ Here is an example with the Node2D class:
                 </description>
             </method>
         </methods>
+        <members>
+            <member name="global_position" type="Vector2" setter="set_global_position" getter="get_global_position" brief="">
+            </member>
+            [...]
+            <member name="z_as_relative" type="bool" setter="set_z_as_relative" getter="is_z_relative" brief="">
+            </member>
+        </members>
         <constants>
         </constants>
     </class>
 
-As you can see, some methods in this class have no description (i.e.
-there is no text between their marks). This can also happen for the
-``description`` and ``brief_description`` of the class, but in our example
-they are already filled. Let's edit the description of the ``rotate()``
-method:
-
-.. code:: xml
-
-    <method name="rotate">
-        <argument index="0" name="degrees" type="float">
-        </argument>
-        <description>
-        Rotates the node of a given number of degrees.
-        </description>
-    </method>
-
-That's all!
-
-You simply have to write any missing text between these marks:
-
--  <description></description>
--  <brief_description></brief_description>
--  <constant></constant>
--  <member></member>
--  <signal></signal>
-
-Describe clearly and shortly what the method does, or what the
-constant, member variable or signal mean. You can include an example
-of use if needed. Try to use grammatically correct English, and check
-the other descriptions to get an impression of the writing style.
 
-For setters/getters, the convention is to describe in depth what the
-method does in the setter, and to say only the minimal in the getter to
-avoid duplication of the contents.
+Use a code editor like Vim, Atom, Code, Notepad++ or anything similar to edit the file quickly. Use the search function to find classes fast, and fold the XML to navigate it faster.
 
-Tags available for improved formatting
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-For more control over the formatting of the help, Godot's XML
-documentation supports various BBcode-like tags which are
-interpreted by both the offline in-editor Help, as well as the
-online documentation (via the reST converter).
+Improve formatting with BBcode style tags
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Those tags are listed below. See existing documentation entries
-for more examples of how to use them properly.
+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 a method of this class    | See [method set_pos].             | See :ref:`set_pos <class_node2d_set_pos>`. |
+| [method methodname]       | Link to a method in this class | See [method set_pos].             | See :ref:`set_pos <class_node2d_set_pos>`. |
 +---------------------------+--------------------------------+-----------------------------------+--------------------------------------------+
-| [method Class.methodname] | Link a method of another class | See [method Node2D.set_pos].      | See :ref:`set_pos <class_node2d_set_pos>`. |
+| [method Class.methodname] | Link to another class's method | See [method Node2D.set_pos].      | See :ref:`set_pos <class_node2d_set_pos>`. |
 +---------------------------+--------------------------------+-----------------------------------+--------------------------------------------+
 | [b] [/b]                  | Bold                           | Some [b]bold[/b] text.            | Some **bold** text.                        |
 +---------------------------+--------------------------------+-----------------------------------+--------------------------------------------+
@@ -371,9 +236,7 @@ for more examples of how to use them properly.
 | [codeblock] [/codeblock]  | Multiline preformatted block   | *See below.*                      | *See below.*                               |
 +---------------------------+--------------------------------+-----------------------------------+--------------------------------------------+
 
-The ``[codeblock]`` is meant to be used for pre-formatted code
-block, using spaces as indentation (tabs will be removed by the
-reST converter). For example:
+Use ``[codeblock]`` for pre-formatted code blocks, using spaces for indentation (the parser will delete tabs). Example:
 
 .. code:: xml
 
@@ -383,7 +246,7 @@ reST converter). For example:
         print(sprite.get_pos())
     [/codeblock]
 
-Which would be rendered as:
+Will display as:
 
 ::
 
@@ -391,15 +254,16 @@ Which would be rendered as:
         var sprite = get_node("Sprite")
         print(sprite.get_pos())
 
+
 I don't know what this method does!
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Not a problem. Leave it behind for now, and don't forget to notify the
-missing methods when you request a pull of your changes. Another
-editor will take care of it.
+No problem. Leave it behind, and list the methods you skipped when you request a pull of your changes. Another writer will take care of it.
+
+You can still have a look at the methods' implementation in Godot's source code on GitHub. Also, if you have doubts, feel free to ask on the `Q&A website <https://godotengine.org/qa/>`__ and on IRC (freenode, #godotengine).
+
+
+Localization
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you wonder what a method does, you can still have a look at its
-implementation in Godot Engine's source code on GitHub. Also, if you
-have a doubt, feel free to ask on the
-`Q&A website <https://godotengine.org/qa/>`__
-and on IRC (freenode, #godotengine).
+Before we translate the documentation, we need to complete and proof-read it in English. We'll work on localization when we get past 90% completion.