Updated README - More info on the getting started section (#623)

README.rst

@@ -54,10 +54,10 @@ Prerequisites:
   if you don't already have one).
 
 
-Let's start:
+Getting Started:
 
 You'll need to fork the `python-docs-fr
-<https://github.com/python/python-docs-fr>`_ clicking its ``Fork``
+<https://github.com/python/python-docs-fr>`_ source repository by clicking its ``Fork``
 button. This creates a copy of the whole project on your github
 account: a place where you have the rights to do modifications.
 
@@ -65,49 +65,59 @@ Step by step:
 
 .. code-block:: bash
 
-    # Git clone your github fork using ssh (replace JulienPalard):
-    git clone git@github.com:JulienPalard/python-docs-fr.git
+    # Clone your github fork with `git` using ssh or https:
+    git clone git@github.com:YOUR_GITHUB_USERNAME/python-docs-fr.git
+    git clone https://github.com:YOUR_GITHUB_USERNAME/python-docs-fr.git
 
-    # Go to the cloned directory:
+    # Go into the cloned directory:
     cd python-docs-fr/
 
     # Add the upstream (the public repository) using HTTPS (won't ask for password):
+    # This is so git knows what/where the upstream is.
     git remote add upstream https://github.com/python/python-docs-fr.git
 
-All the translations must be made on the latest release.
-We never translate on an oldest version, by example, the latest python release
-is python 3.7, we don't want to translate directly on the python 3.5 release.
-If needed translations would be backported on the oldest versions by the
-`documentation team <https://www.python.org/dev/peps/pep-8015/#documentation-team>`.
+Next, you need to find a file to work on.
+You can use `potodo <https://github.com/seluj78/potodo>`, a tool made to find ``po`` to do.
+Install it using pip (``pip install potodo``) in a ``python3.7`` environement.
+Then run the command ``potodo`` in your cloned fork.
+From the list returned by the command, you can choose any file that is not reserved.
 
-First, you need to find a file to work on. You can use `potodo <https://github.com/seluj78/potodo>`.
-Install it (``pip install potodo`` in a venv) and then run the command
-`potodo` in your cloned fork. 
-From the list it spits out, you can choose any file that is not
-reserved. We recommend not starting with a file from ``c-api`` as it is very technical.
+**We recommend not starting with a file from ``c-api`` as it is very technical.**
 
-Once you've choosen a file, please open an issue telling you're
-working on it, to block someone from working on it.
+Once you've choosen a file to work one, please open an `issue on github <https://github.com/python/python-docs-fr>` in the format of `I'm working on FOLDER/FILE.po`. This is done to update ``potodo`` as it checks the github API for reserved ``.po`` files in issues and pull requests.
 
-Now you're ready to start a work session, each time you'll start a new task, start here:
+Now you're ready to start a work session. Each time you'll start a new file, start here:
 
 .. code-block:: bash
 
     # To work, we'll need a branch, based on an up-to-date (freshly fetched)
-    # upstream/3.7 branch, let's say we'll work on glossary so we name
-    # the branch "glossary":
+    # upstream/3.7 branch. We will name our branch "library-sys" but you shall name yours
+    # whatever you want. Usually you'll name a branch based on the file you're working on.
+    # For example, If you're working on "library/venv.po" you can name your branch "library-venv"
+    
+    # Update your local version to the latest
     git fetch upstream
-    git checkout -b glossary upstream/3.7
+    # Create a new branch named "library-sys" based on "upstream/3.7"
+    git checkout -b library-sys upstream/3.7
 
     # You can now work on the file, typically using poedit,
-    poedit directory/file.po
+    # Of course, replace "library/sys.po" by the file you've chose earlier
+    poedit library/sys.po
 
-    # When everything is clear (syntax errors from Sphinx, html rendering,
-    # semantics, typography),
+    # When you are done translating, you can run pospell (pip install pospell).
+    # This tool was made to check if you don't have any french mistakes.
+    # You can run the following command: pospell -p dict -l fr_FR **/*.po to check all files
+    # or replace **/*.po by your specific file (recommended).
+
+    # You can then run powrap (pip install powrap) which will rewrap
+    # You modified file to the correct line length of `80`.
+    # Run this command: `powrap **/*.po` or replace `**/*.po` with your modified file.
+
+    # When everything powrap and pospell passes without errors,
     # you can commit your work with a nice explicit message:
-    git commit -a -m "Working on glossary."
+    git commit -a -m "Working on library/sys.po."
 
-    # Then push your modifications to your github clone,
+    # Then push your modifications to your github fork,
     # as they are ephemeral branches, let's not configure git to track them all,
     # "origin HEAD" is a "special" syntax to say "Push on origin,
     # on a branch with the same name as the local one",
@@ -145,6 +155,13 @@ Before commiting, you should use `grammalecte
 <https://grammalecte.net/>`_ to check for your translations.
 
 
+All the translations must be made on the latest release.
+We never translate on an oldest version. For example, if the latest python release
+is Python 3.7, we don't want to translate directly on the python 3.5 release.
+If needed translations would be backported on the oldest versions by the
+`documentation team <https://www.python.org/dev/peps/pep-8015/#documentation-team>`.
+
+
 What to translate
 ~~~~~~~~~~~~~~~~~