Merge pull request #2550 from wallabag/reorder-documentation

Reordered documentation

19 files changed, 499 insertions, 406 deletions

diff --git a/docs/en/developer/asynchronous.rst b/docs/en/developer/asynchronous.rst
new file mode 100644
index 00000000..6a991cf6
--- /dev/null
+++ b/docs/en/developer/asynchronous.rst
@@ -0,0 +1,159 @@
+Asynchronous tasks
+==================
+
+In order to launch asynchronous tasks (useful for huge imports for example), we can use RabbitMQ or Redis.
+
+Install RabbitMQ for asynchronous tasks
+---------------------------------------
+
+Requirements
+^^^^^^^^^^^^
+
+You need to have RabbitMQ installed on your server.
+
+Installation
+^^^^^^^^^^^^
+
+.. code:: bash
+
+  wget https://www.rabbitmq.com/rabbitmq-signing-key-public.asc
+  apt-key add rabbitmq-signing-key-public.asc
+  apt-get update
+  apt-get install rabbitmq-server
+
+Configuration and launch
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code:: bash
+
+  rabbitmq-plugins enable rabbitmq_management # (useful to have a web interface, available at http://localhost:15672/ (guest/guest)
+  rabbitmq-server -detached
+
+Stop RabbitMQ
+^^^^^^^^^^^^^
+
+.. code:: bash
+
+  rabbitmqctl stop
+
+
+Configure RabbitMQ in wallabag
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Edit your ``app/config/parameters.yml`` file to edit RabbitMQ configuration. The default one should be ok:
+
+.. code:: yaml
+
+    rabbitmq_host: localhost
+    rabbitmq_port: 5672
+    rabbitmq_user: guest
+    rabbitmq_password: guest
+
+Enable RabbitMQ in wallabag
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In internal settings, in the **Import** section, enable RabbitMQ (with the value 1).
+
+Launch RabbitMQ consumer
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Depending on which service you want to import from you need to enable one (or many if you want to support many) cron job:
+
+.. code:: bash
+
+  # for Pocket import
+  bin/console rabbitmq:consumer -e=prod import_pocket -w
+
+  # for Readability import
+  bin/console rabbitmq:consumer -e=prod import_readability -w
+
+  # for Instapaper import
+  bin/console rabbitmq:consumer -e=prod import_instapaper -w
+
+  # for wallabag v1 import
+  bin/console rabbitmq:consumer -e=prod import_wallabag_v1 -w
+
+  # for wallabag v2 import
+  bin/console rabbitmq:consumer -e=prod import_wallabag_v2 -w
+
+  # for Firefox import
+  bin/console rabbitmq:consumer -e=prod import_firefox -w
+
+  # for Chrome import
+  bin/console rabbitmq:consumer -e=prod import_chrome -w
+
+Install Redis for asynchronous tasks
+------------------------------------
+
+In order to launch asynchronous tasks (useful for huge imports for example), we can use Redis.
+
+Requirements
+^^^^^^^^^^^^
+
+You need to have Redis installed on your server.
+
+Installation
+^^^^^^^^^^^^
+
+.. code:: bash
+
+  apt-get install redis-server
+
+Launch
+^^^^^^
+
+The server might be already running after installing, if not you can launch it using:
+
+.. code:: bash
+
+  redis-server
+
+
+Configure Redis in wallabag
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Edit your ``app/config/parameters.yml`` file to edit Redis configuration. The default one should be ok:
+
+.. code:: yaml
+
+    redis_host: localhost
+    redis_port: 6379
+
+Enable Redis in wallabag
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+In internal settings, in the **Import** section, enable Redis (with the value 1).
+
+Launch Redis consumer
+^^^^^^^^^^^^^^^^^^^^^
+
+Depending on which service you want to import from you need to enable one (or many if you want to support many) cron job:
+
+.. code:: bash
+
+  # for Pocket import
+  bin/console wallabag:import:redis-worker -e=prod pocket -vv >> /path/to/wallabag/var/logs/redis-pocket.log
+
+  # for Readability import
+  bin/console wallabag:import:redis-worker -e=prod readability -vv >> /path/to/wallabag/var/logs/redis-readability.log
+
+  # for Instapaper import
+  bin/console wallabag:import:redis-worker -e=prod instapaper -vv >> /path/to/wallabag/var/logs/redis-instapaper.log
+
+  # for wallabag v1 import
+  bin/console wallabag:import:redis-worker -e=prod wallabag_v1 -vv >> /path/to/wallabag/var/logs/redis-wallabag_v1.log
+
+  # for wallabag v2 import
+  bin/console wallabag:import:redis-worker -e=prod wallabag_v2 -vv >> /path/to/wallabag/var/logs/redis-wallabag_v2.log
+
+  # for Firefox import
+  bin/console wallabag:import:redis-worker -e=prod firefox -vv >> /path/to/wallabag/var/logs/redis-firefox.log
+
+  # for Chrome import
+  bin/console wallabag:import:redis-worker -e=prod instapaper -vv >> /path/to/wallabag/var/logs/redis-chrome.log
+
+If you want to launch the import only for some messages and not all, you can specify this number (here 12) and the worker will stop right after the 12th message :
+
+.. code:: bash
+
+  bin/console wallabag:import:redis-worker -e=prod pocket -vv --maxIterations=12
diff --git a/docs/en/developer/rabbitmq.rst b/docs/en/developer/rabbitmq.rst
deleted file mode 100644
index 7ee8a5ce..00000000
--- a/docs/en/developer/rabbitmq.rst
+++ /dev/null
@@ -1,80 +0,0 @@
-Install RabbitMQ for asynchronous tasks
-=======================================
-
-In order to launch asynchronous tasks (useful for huge imports for example), we can use RabbitMQ.
-
-Requirements
-------------
-
-You need to have RabbitMQ installed on your server.
-
-Installation
-~~~~~~~~~~~~
-
-.. code:: bash
-
-  wget https://www.rabbitmq.com/rabbitmq-signing-key-public.asc
-  apt-key add rabbitmq-signing-key-public.asc
-  apt-get update
-  apt-get install rabbitmq-server
-
-Configuration and launch
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. code:: bash
-
-  rabbitmq-plugins enable rabbitmq_management # (useful to have a web interface, available at http://localhost:15672/ (guest/guest)
-  rabbitmq-server -detached
-
-Stop RabbitMQ
-~~~~~~~~~~~~~
-
-.. code:: bash
-
-  rabbitmqctl stop
-
-
-Configure RabbitMQ in wallabag
-------------------------------
-
-Edit your ``app/config/parameters.yml`` file to edit RabbitMQ configuration. The default one should be ok:
-
-.. code:: yaml
-
-    rabbitmq_host: localhost
-    rabbitmq_port: 5672
-    rabbitmq_user: guest
-    rabbitmq_password: guest
-
-Enable RabbitMQ in wallabag
----------------------------
-
-In internal settings, in the **Import** section, enable RabbitMQ (with the value 1).
-
-Launch RabbitMQ consumer
-------------------------
-
-Depending on which service you want to import from you need to enable one (or many if you want to support many) cron job:
-
-.. code:: bash
-
-  # for Pocket import
-  bin/console rabbitmq:consumer -e=prod import_pocket -w
-
-  # for Readability import
-  bin/console rabbitmq:consumer -e=prod import_readability -w
-
-  # for Instapaper import
-  bin/console rabbitmq:consumer -e=prod import_instapaper -w
-
-  # for wallabag v1 import
-  bin/console rabbitmq:consumer -e=prod import_wallabag_v1 -w
-
-  # for wallabag v2 import
-  bin/console rabbitmq:consumer -e=prod import_wallabag_v2 -w
-
-  # for Firefox import
-  bin/console rabbitmq:consumer -e=prod import_firefox -w
-
-  # for Chrome import
-  bin/console rabbitmq:consumer -e=prod import_chrome -w
diff --git a/docs/en/developer/redis.rst b/docs/en/developer/redis.rst
deleted file mode 100644
index ea084e66..00000000
--- a/docs/en/developer/redis.rst
+++ /dev/null
@@ -1,75 +0,0 @@
-Install Redis for asynchronous tasks
-====================================
-
-In order to launch asynchronous tasks (useful for huge imports for example), we can use Redis.
-
-Requirements
-------------
-
-You need to have Redis installed on your server.
-
-Installation
-~~~~~~~~~~~~
-
-.. code:: bash
-
-  apt-get install redis-server
-
-Launch
-~~~~~~
-
-The server might be already running after installing, if not you can launch it using:
-
-.. code:: bash
-
-  redis-server
-
-
-Configure Redis in wallabag
----------------------------
-
-Edit your ``app/config/parameters.yml`` file to edit Redis configuration. The default one should be ok:
-
-.. code:: yaml
-
-    redis_host: localhost
-    redis_port: 6379
-
-Enable Redis in wallabag
-------------------------
-
-In internal settings, in the **Import** section, enable Redis (with the value 1).
-
-Launch Redis consumer
----------------------
-
-Depending on which service you want to import from you need to enable one (or many if you want to support many) cron job:
-
-.. code:: bash
-
-  # for Pocket import
-  bin/console wallabag:import:redis-worker -e=prod pocket -vv >> /path/to/wallabag/var/logs/redis-pocket.log
-
-  # for Readability import
-  bin/console wallabag:import:redis-worker -e=prod readability -vv >> /path/to/wallabag/var/logs/redis-readability.log
-
-  # for Instapaper import
-  bin/console wallabag:import:redis-worker -e=prod instapaper -vv >> /path/to/wallabag/var/logs/redis-instapaper.log
-
-  # for wallabag v1 import
-  bin/console wallabag:import:redis-worker -e=prod wallabag_v1 -vv >> /path/to/wallabag/var/logs/redis-wallabag_v1.log
-
-  # for wallabag v2 import
-  bin/console wallabag:import:redis-worker -e=prod wallabag_v2 -vv >> /path/to/wallabag/var/logs/redis-wallabag_v2.log
-
-  # for Firefox import
-  bin/console wallabag:import:redis-worker -e=prod firefox -vv >> /path/to/wallabag/var/logs/redis-firefox.log
-
-  # for Chrome import
-  bin/console wallabag:import:redis-worker -e=prod instapaper -vv >> /path/to/wallabag/var/logs/redis-chrome.log
-
-If you want to launch the import only for some messages and not all, you can specify this number (here 12) and the worker will stop right after the 12th message :
-
-.. code:: bash
-
-  bin/console wallabag:import:redis-worker -e=prod pocket -vv --maxIterations=12
diff --git a/docs/en/index.rst b/docs/en/index.rst
index 0ead261b..77425bfa 100644
--- a/docs/en/index.rst
+++ b/docs/en/index.rst
@@ -8,10 +8,6 @@ wallabag documentation
 **wallabag** is a read-it-later application: it saves a web page by
 keeping content only. Elements like navigation or ads are deleted.
 
-.. tip::
-
-    This documentation is about wallabag v2. If you want to read documentation for wallabag v1, `please have a look here <https://github.com/wallabag/documentation>`__.
-
 The main documentation for this application is organized into a couple sections:
 
 * :ref:`user-docs`
@@ -20,7 +16,7 @@ The main documentation for this application is organized into a couple sections:
 The documentation is available in other languages:
 
 * `Documentation en français <http://doc.wallabag.org/fr/master/>`_
-* `Deutsch Dokumentation <http://doc.wallabag.org/de/master/>`_
+* `Dokumentation in Deutsch <http://doc.wallabag.org/de/master/>`_
 
 .. _user-docs:
 
@@ -28,25 +24,19 @@ The documentation is available in other languages:
    :maxdepth: 2
    :caption: User documentation
 
-   user/faq
    user/installation
-   user/upgrade-2.0.x-2.1.1
-   user/upgrade-2.1.x-2.1.y
-   user/migration
+   user/upgrade
+   user/configuration
    user/import
    user/create_account
-   user/login
-   user/configuration
-   user/first_article
+   user/articles
    user/errors_during_fetching
-   user/annotations
-   user/download_articles
-   user/share
    user/filters
    user/tags
    user/android
    user/parameters
    user/backup
+   user/faq
 
 .. _dev-docs:
 
@@ -59,5 +49,4 @@ The documentation is available in other languages:
    developer/documentation
    developer/translate
    developer/maintenance
-   developer/redis
-   developer/rabbitmq
+   developer/asynchronous
diff --git a/docs/en/user/android.rst b/docs/en/user/android.rst
index 91dcb2fc..e286bb3b 100644
--- a/docs/en/user/android.rst
+++ b/docs/en/user/android.rst
@@ -1,13 +1,11 @@
-Android App
-===========
-
+Android application
+===================
 
 Purpose of this document
 ------------------------
 
 This document describes how you can setup your Android application to work with your wallabag instance. There is no difference in this procedure for wallabag v1 or v2.
 
-
 Steps to configure your app
 ---------------------------
 
@@ -23,7 +21,7 @@ Just confirm that message and you get redirected to the settings screen.
     :alt: Settings screen
     :align: center
 
-Fill in your wallabag data. You need to enter your wallabag address. It is important that this URL does not end with a slash. Also add your wallabag credentials to the user name and password field.
+Fill in your wallabag data. You need to enter your wallabag address. **It is important that this URL does not end with a slash**. Also add your wallabag credentials to the user name and password field.
 
 .. image:: ../../img/user/android_configuration_filled_in.en.png
     :alt: Filled in settings
@@ -59,49 +57,39 @@ Now you need to scroll to the bottom of the settings menu. Of course you can adj
     :alt: Bottom of the settings screen
     :align: center
 
-After hitting the save button, you get the following screen. The app proposes to initiate a syncronisation process to update your feeds of articles. It is recommended to acknowledge this action and press Yes.
+After hitting the save button, you get the following screen. The app proposes to initiate a synchronization process to update your feeds of articles. It is recommended to acknowledge this action and press Yes.
 
 .. image:: ../../img/user/android_configuration_saved_feed_update.en.png
     :alt: Settings saved the first time
     :align: center
 
-Finally after the synchronisation finished successfully, you are presented to the list of unread articles.
+Finally after the synchronization finished successfully, you are presented to the list of unread articles.
 
 .. image:: ../../img/user/android_unread_feed_synced.en.png
     :alt: Filled article list cause feeds successfully synchronized
     :align: center
 
-
-
 Known limitations
 -----------------
 
-2FA
-~~~
+Two factor authentication (2FA)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Currently the Android application does not support two-factor authentication. You should disable that to get the application working.
 
-
 Limited amount of articles with wallabag v2
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In your wallabag web instance you can configure how many items are part of the RSS feed. This option did not exist in wallabag v1, where all articles were part of the feed. So if you set the amount of articles being displayed greater than the number of items being content of your RSS feed, you will only see the number of items in your RSS feed.
 
-
 SSL/TLS encryption
 ~~~~~~~~~~~~~~~~~~
 
 If you can reach your wallabag web instance via HTTPS, you should use that. Especially if your HTTP URL redirects you to the HTTPS one. Currently, the app cannot handle that redirect properly.
 
-
 References
 ----------
 
-`Source code of the Android application <https://github.com/wallabag/android-app>`_
-
-`Android Application on F-Droid <https://f-droid.org/repository/browse/?fdfilter=wallabag&fdid=fr.gaulupeau.apps.InThePoche>`_
-
-`Android Application on Google Play <https://play.google.com/store/apps/details?id=fr.gaulupeau.apps.InThePoche>`_
-
-`Support chat <https://gitter.im/wallabag/wallabag>`_
-
+- `Source code of the Android application <https://github.com/wallabag/android-app>`_
+- `Android Application on F-Droid <https://f-droid.org/repository/browse/?fdfilter=wallabag&fdid=fr.gaulupeau.apps.InThePoche>`_
+- `Android Application on Google Play <https://play.google.com/store/apps/details?id=fr.gaulupeau.apps.InThePoche>`_
diff --git a/docs/en/user/annotations.rst b/docs/en/user/annotations.rst
deleted file mode 100644
index fab854aa..00000000
--- a/docs/en/user/annotations.rst
+++ /dev/null
@@ -1,24 +0,0 @@
-Annotations
-===========
-
-In each article you read, you can write annotations. It's easier to understand with some pictures.
-
-Select the part of the article that you want to annotate and click on the pencil:
-
-.. image:: ../../img/user/annotations_1.png
-   :alt: Select your text
-   :align: center
-
-Then, write your annotation:
-
-.. image:: ../../img/user/annotations_2.png
-   :alt: Write your annotation
-   :align: center
-
-The text is now highlighted and you can read your annotation if you move the mouse cursor over it.
-
-.. image:: ../../img/user/annotations_3.png
-   :alt: Read your annotation
-   :align: center
-
-You can create as many annotations as you wish.
diff --git a/docs/en/user/articles.rst b/docs/en/user/articles.rst
new file mode 100644
index 00000000..16b3b0d2
--- /dev/null
+++ b/docs/en/user/articles.rst
@@ -0,0 +1,116 @@
+Articles
+========
+
+Save your first article
+-----------------------
+
+The main purpose of wallabag is to save web articles. You have many ways to do it. If you think that the article is wrong displayed, `you can read this documentation <http://doc.wallabag.org/en/master/user/errors_during_fetching.html>`_.
+
+By using a bookmarklet
+^^^^^^^^^^^^^^^^^^^^^^
+
+On the ``Howto`` page, you have a ``Bookmarklet`` tab. Drag and drop the ``bag it!``
+link to your bookmarks bar of your browser.
+
+Now, each time you're reading an article on the web and you want to save it,
+click on the ``bag it!`` link in your bookmarks bar. The article is saved.
+
+By using the classic form
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In the top bar of your screen, you have 3 icons. With the first one, a plus sign,
+you can easily save a new article.
+
+.. image:: ../../img/user/topbar.png
+   :alt: Top bar
+   :align: center
+
+Click on it to display a new field, paste the article URL inside and press your
+``Return`` key. The article is saved.
+
+By using a browser add-on
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Firefox
+"""""""
+
+You can download the `Firefox addon here <https://addons.mozilla.org/firefox/addon/wallabag-v2/>`_.
+
+Chrome
+""""""
+
+You can download the `Chrome addon here <https://chrome.google.com/webstore/detail/wallabagger/gbmgphmejlcoihgedabhgjdkcahacjlj?hl=fr>`_.
+
+By using your smarphone application
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Android
+"""""""
+
+You can download the `Android application here <https://play.google.com/store/apps/details?id=fr.gaulupeau.apps.InThePoche>`_.
+
+Windows Phone
+"""""""""""""
+
+You can downlaod the `Windows Phone application here <https://www.microsoft.com/store/apps/9nblggh5x3p6>`_.
+
+Download your articles
+----------------------
+
+You can download each article in several formats: ePUB, MOBI, PDF, XML, JSON, CSV.
+
+On the article view, click on this icon, in the sidebar:
+
+.. image:: ../../img/user/download_article.png
+   :alt: download article
+   :align: center
+
+You can also download a full category (unread, starred, archive) in these formats.
+For example, on **Unread** view, click on this icon in the top bar:
+
+.. image:: ../../img/user/download_articles.png
+   :alt: download articles
+   :align: center
+
+Share your articles
+-------------------
+
+When you're reading an article, you can share it. Just click on the share button:
+
+.. image:: ../../img/user/share.png
+   :alt: share article
+   :align: center
+
+Now, you can share the article:
+
+- with a public URL (you'll have a light view of the article)
+- with a tweet
+- into your Shaarli
+- with a post in Diaspora*
+- to Carrot
+- with an email
+
+Annotate your articles
+----------------------
+
+In each article you read, you can write annotations. It's easier to understand with some pictures.
+
+Select the part of the article that you want to annotate and click on the pencil:
+
+.. image:: ../../img/user/annotations_1.png
+   :alt: Select your text
+   :align: center
+
+Then, write your annotation:
+
+.. image:: ../../img/user/annotations_2.png
+   :alt: Write your annotation
+   :align: center
+
+The text is now highlighted and you can read your annotation if you move the mouse cursor over it.
+
+.. image:: ../../img/user/annotations_3.png
+   :alt: Read your annotation
+   :align: center
+
+You can create as many annotations as you wish.
diff --git a/docs/en/user/backup.rst b/docs/en/user/backup.rst
index 51721000..f8b480a3 100644
--- a/docs/en/user/backup.rst
+++ b/docs/en/user/backup.rst
@@ -1,5 +1,6 @@
 Backup wallabag
 ===============
+
 Because sometimes you may do a mistake with your wallabag and lose data or in case you need to move your wallabag to another server you want to backup your data.
 This articles describes what you need to backup.
 
@@ -22,4 +23,4 @@ To backup the SQLite database, you just need to copy the directory `data/db` fro
 
 Images
 ------
-The images retrieved by wallabag are stored under `data/assets/images` (the images storage will be implemented in wallabag 2.2).
+The images retrieved by wallabag are stored under `web/assets/images` (the images storage will be implemented in wallabag 2.2).
diff --git a/docs/en/user/configuration.rst b/docs/en/user/configuration.rst
index a6edcd4a..2c1385a8 100644
--- a/docs/en/user/configuration.rst
+++ b/docs/en/user/configuration.rst
@@ -48,8 +48,8 @@ User information
 
 You can change your name, your email address and enable ``Two factor authentication``.
 
-Two factor authentication
-~~~~~~~~~~~~~~~~~~~~~~~~~
+Two factor authentication (2FA)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
     Two-factor authentication (also known as 2FA) is a technology patented in 1984
     that provides identification of users by means of the combination of two different components.
diff --git a/docs/en/user/create_account.rst b/docs/en/user/create_account.rst
index 2e883c88..8c43867d 100644
--- a/docs/en/user/create_account.rst
+++ b/docs/en/user/create_account.rst
@@ -1,5 +1,8 @@
-Create an account
-=================
+Create an account and authentication
+====================================
+
+Register
+--------
 
 On the login page, click on ``Register`` button.
 
@@ -23,3 +26,17 @@ Your account is now activated.
 .. image:: ../../img/user/activated_account.png
    :alt: Welcome on board!
    :align: center
+
+Login
+-----
+
+Your account is now enabled, congratulations!
+
+To login to wallabag, fill the form on login page.
+
+If you are on your personal computer and you want to stay connected,
+you can check the ``Keep me logged in`` checkbox: wallabag will remember you for one year.
+
+.. image:: ../../img/user/login_form.png
+   :alt: Login form
+   :align: center
diff --git a/docs/en/user/download_articles.rst b/docs/en/user/download_articles.rst
deleted file mode 100644
index 4813776d..00000000
--- a/docs/en/user/download_articles.rst
+++ /dev/null
@@ -1,17 +0,0 @@
-Download articles
-=================
-
-You can download each article in several formats: ePUB, MOBI, PDF, XML, JSON, CSV.
-
-On the article view, click on this icon, in the sidebar:
-
-.. image:: ../../img/user/download_article.png
-   :alt: download article
-   :align: center
-
-You can also download a full category (unread, starred, archive) in these formats.
-For example, on **Unread** view, click on this icon in the top bar:
-
-.. image:: ../../img/user/download_articles.png
-   :alt: download articles
-   :align: center
diff --git a/docs/en/user/errors_during_fetching.rst b/docs/en/user/errors_during_fetching.rst
index 6684563a..c5e18d3b 100644
--- a/docs/en/user/errors_during_fetching.rst
+++ b/docs/en/user/errors_during_fetching.rst
@@ -12,9 +12,7 @@ There may be several reasons:
 How can I help to fix that?
 ---------------------------
 
-You can `sending us an email with the article's URL <mailto:hello@wallabag.org>`_.
-
-Or you can also try to fix this problem by yourself (so we can be focused on improving wallabag internally instead of writing siteconfig :) ).
+You can try to fix this problem by yourself (so we can be focused on improving wallabag internally instead of writing siteconfig :) ).
 
 You can try to see if it works here: `http://f43.me/feed/test <http://f43.me/feed/test>`_ (it uses almost the same system as wallabag to retrieve content).
 
diff --git a/docs/en/user/filters.rst b/docs/en/user/filters.rst
index ad06819b..4d1df6eb 100644
--- a/docs/en/user/filters.rst
+++ b/docs/en/user/filters.rst
@@ -1,7 +1,7 @@
-Filters
-=======
+Retrieve your articles thanks to filters
+========================================
 
-To retrieve articles easier, you can use filters.
+To retrieve articles easily, you can use filters.
 Click on the third icon in the top bar.
 
 .. image:: ../../img/user/topbar.png
diff --git a/docs/en/user/import.rst b/docs/en/user/import.rst
index 38cd30c1..a6754fa0 100644
--- a/docs/en/user/import.rst
+++ b/docs/en/user/import.rst
@@ -1,8 +1,20 @@
-Migrate from a third service
-============================
+Migrate from ...
+================
 
-From Pocket
------------
+In wallabag 2.x, you can import data from: 
+
+- `Pocket <#id1>`_ 
+- `Readability <#id2>`_ 
+- `Instapaper <#id4>`_ 
+- `wallabag 1.x <#id6>`_ 
+- `wallabag 2.x <#id7>`_ 
+
+We also developed `a script to execute migrations via command-line interface <#import-via-command-line-interface-cli>`_.
+
+Because imports can take ages, we developed an asynchronous tasks system. `You can read the documentation here <http://doc.wallabag.org/fr/master/developer/asynchronous.html>`_ (for experts).
+
+Pocket
+------
 
 Create a new application on Pocket
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -29,8 +41,8 @@ and then on ``Connect to Pocket and import data``.
 You need to authorize wallabag to interact with your Pocket account.
 Your data will be imported. Data import can be a demanding process for your server.
 
-From Readability
-----------------
+Readability
+-----------
 
 Export your Readability data
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -45,8 +57,8 @@ and then select your json file and upload it.
 
 Your data will be imported. Data import can be a demanding process for your server.
 
-From Instapaper
----------------
+Instapaper
+----------
 
 Export your Instapaper data
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -61,7 +73,66 @@ and then select your CSV file and upload it.
 
 Your data will be imported. Data import can be a demanding process for your server.
 
-From HTML or JSON file
-----------------------
+wallabag 1.x
+------------
+
+If you were using wallabag v1.x, you need to export your data before migrating to wallabag v2.x, because the application and its database changed a lot. In your old wallabag installation, you can export your data, which can be done on the Config page of your old wallabag installation.
+
+.. image:: ../../img/user/export_v1.png
+   :alt: Exporting from wallabag v1
+   :align: center
+
+.. note::
+    If you have multiple accounts on the same instance of wallabag, each user must export from v1 and import into v2 its data.
+
+.. note::
+    If you encounter issues during the export or the import, don't hesitate to `ask for support <https://www.wallabag.org/pages/support.html>`__.
+
+When you have retrieved the json file containing your entries, you can install wallabag v2 if needed by following `the standard procedure <http://doc.wallabag.org/en/master/user/installation.html>`__.
+
+After creating an user account on your new wallabag v2 instance, you must head over to the `Import` section and select `Import from wallabag v1`. Select your json file and upload it.
+
+.. image:: ../../img/user/import_wallabagv1.png
+   :alt: Import from wallabag v1
+   :align: center
+
+wallabag 2.x
+------------
+
+From the previous wallabag instance on which you were before, go to `All articles`, then export these articles as json.
+
+.. image:: ../../img/user/export_v2.png
+   :alt: Export depuis wallabag v2
+   :align: center
+
+From your new wallabag instance, create your user account and click on the link in the menu to proceed to import. Choose import from wallabag v2 and select your json file to upload it.
+
+.. note::
+    If you encounter issues during the export or the import, don't hesitate to `ask for support <https://www.wallabag.org/pages/support.html>`__.
+
+Import via command-line interface (CLI)
+---------------------------------------
+
+If you have a CLI access on your web server, you can execute this command to import your wallabag v1 export:
+
+::
+
+    bin/console wallabag:import 1 ~/Downloads/wallabag-export-1-2016-04-05.json --env=prod
+
+Please replace values:
+
+* ``1`` is the user identifier in database (The ID of the first user created on wallabag is 1)
+* ``~/Downloads/wallabag-export-1-2016-04-05.json`` is the path of your wallabag v1 export
+
+If you want to mark all these entries as read, you can add the ``--markAsRead`` option.
+
+To import a wallabag v2 file, you need to add the option ``--importer=v2``.
+
+You'll have this in return:
+
+::
 
-*Feature not yet implemented in wallabag v2.*
+    Start : 05-04-2016 11:36:07 ---
+    403 imported
+    0 already saved
+    End : 05-04-2016 11:36:09 ---
diff --git a/docs/en/user/login.rst b/docs/en/user/login.rst
deleted file mode 100644
index e66089bd..00000000
--- a/docs/en/user/login.rst
+++ /dev/null
@@ -1,13 +0,0 @@
-Login
-=====
-
-Your account is now enabled, congratulations!
-
-To login to wallabag, fill the form on login page.
-
-If you are on your personal computer and you want to stay connected,
-you can check the ``Keep me logged in`` checkbox: wallabag will remember you for one year.
-
-.. image:: ../../img/user/login_form.png
-   :alt: Login form
-   :align: center
diff --git a/docs/en/user/migration.rst b/docs/en/user/migration.rst
deleted file mode 100644
index 42062796..00000000
--- a/docs/en/user/migration.rst
+++ /dev/null
@@ -1,66 +0,0 @@
-Migrate from v1 or v2
-=====================
-
-From wallabag 1.x
------------------
-
-If you were using wallabag v1.x, you need to export your data before migrating to wallabag v2.x, because the application and its database changed a lot. In your old wallabag installation, you can export your data, which can be done on the Config page of your old wallabag installation.
-
-.. image:: ../../img/user/export_v1.png
-   :alt: Exporting from wallabag v1
-   :align: center
-
-.. note::
-    If you have multiple accounts on the same instance of wallabag, each user must export from v1 and import into v2 its data.
-
-.. note::
-    If you encounter issues during the export or the import, don't hesitate to `ask for support <https://www.wallabag.org/pages/support.html>`__.
-
-When you have retrieved the json file containing your entries, you can install wallabag v2 if needed by following `the standard procedure <http://doc.wallabag.org/en/master/user/installation.html>`__.
-
-After creating an user account on your new wallabag v2 instance, you must head over to the `Import` section and select `Import from wallabag v1`. Select your json file and upload it.
-
-.. image:: ../../img/user/import_wallabagv1.png
-   :alt: Import from wallabag v1
-   :align: center
-
-From wallabag 2.x
------------------
-
-From the previous wallabag instance on which you were before, go to `All articles`, then export these articles as json.
-
-.. image:: ../../img/user/export_v2.png
-   :alt: Export depuis wallabag v2
-   :align: center
-
-From your new wallabag instance, create your user account and click on the link in the menu to proceed to import. Choose import from wallabag v2 and select your json file to upload it.
-
-.. note::
-    If you encounter issues during the export or the import, don't hesitate to `ask for support <https://www.wallabag.org/pages/support.html>`__.
-
-Import via command-line interface (CLI)
----------------------------------------
-
-If you have a CLI access on your web server, you can execute this command to import your wallabag v1 export:
-
-::
-
-    bin/console wallabag:import 1 ~/Downloads/wallabag-export-1-2016-04-05.json --env=prod
-
-Please replace values:
-
-* ``1`` is the user identifier in database (The ID of the first user created on wallabag is 1)
-* ``~/Downloads/wallabag-export-1-2016-04-05.json`` is the path of your wallabag v1 export
-
-If you want to mark all these entries as read, you can add the ``--markAsRead`` option.
-
-To import a wallabag v2 file, you need to add the option ``--importer=v2``.
-
-You'll have this in return:
-
-::
-
-    Start : 05-04-2016 11:36:07 ---
-    403 imported
-    0 already saved
-    End : 05-04-2016 11:36:09 ---
diff --git a/docs/en/user/parameters.rst b/docs/en/user/parameters.rst
index 6cbd5ae4..2b02a34d 100644
--- a/docs/en/user/parameters.rst
+++ b/docs/en/user/parameters.rst
@@ -1,5 +1,48 @@
 What is the meaning of the parameters?
 ======================================
+
+Default `parameters.yml` file
+-----------------------------
+
+Here is the last version of the default `app/config/parameters.yml` file. Be sure that yours respects this one.
+If you don't know which value you need to set, please leave the default one.
+
+.. code-block:: yml
+
+    parameters:
+        database_driver: pdo_sqlite
+        database_host: 127.0.0.1
+        database_port: null
+        database_name: symfony
+        database_user: root
+        database_password: null
+        database_path: '%kernel.root_dir%/../data/db/wallabag.sqlite'
+        database_table_prefix: wallabag_
+        database_socket: null
+        mailer_transport: smtp
+        mailer_host: 127.0.0.1
+        mailer_user: null
+        mailer_password: null
+        locale: en
+        secret: ovmpmAWXRCabNlMgzlzFXDYmCFfzGv
+        twofactor_auth: true
+        twofactor_sender: no-reply@wallabag.org
+        fosuser_registration: true
+        fosuser_confirmation: true
+        from_email: no-reply@wallabag.org
+        rss_limit: 50
+        rabbitmq_host: localhost
+        rabbitmq_port: 5672
+        rabbitmq_user: guest
+        rabbitmq_password: guest
+        redis_scheme: tcp
+        redis_host: localhost
+        redis_port: 6379
+        redis_path: null
+
+Meaning of each parameter
+-------------------------
+
 .. csv-table:: Database parameters
    :header: "name", "default", "description"
 
diff --git a/docs/en/user/upgrade-2.1.x-2.1.y.rst b/docs/en/user/upgrade-2.1.x-2.1.y.rst
deleted file mode 100644
index fb41a07b..00000000
--- a/docs/en/user/upgrade-2.1.x-2.1.y.rst
+++ /dev/null
@@ -1,30 +0,0 @@
-Upgrading from 2.1.x to 2.1.y
-=============================
-
-Upgrade on a dedicated web server
----------------------------------
-
-The last release is published on https://www.wallabag.org/pages/download-wallabag.html. In order to upgrade your wallabag installation and get the last version, run the following commands in you wallabag folder (replace ``2.1.3`` by the last release number):
-
-::
-
-    make update
-
-Upgrade on a shared hosting
----------------------------
-
-Backup your ``app/config/parameters.yml`` file.
-
-Download the last release of wallabag:
-
-.. code-block:: bash
-
-    wget http://wllbg.org/latest-v2-package && tar xvf latest-v2-package
-
-You will find the `md5 hash of the latest package on our website <https://www.wallabag.org/pages/download-wallabag.html>`_.
-
-Extract the archive in your wallabag folder and replace ``app/config/parameters.yml`` with yours.
-
-If you use SQLite, you must also copy your ``data/`` folder inside the new installation.
-
-Empty ``var/cache`` folder.
diff --git a/docs/en/user/upgrade-2.0.x-2.1.1.rst b/docs/en/user/upgrade.rst
index 3b39fc8c..544d57eb 100644
--- a/docs/en/user/upgrade-2.0.x-2.1.1.rst
+++ b/docs/en/user/upgrade.rst
@@ -1,12 +1,21 @@
+Upgrade your wallabag installation
+==================================
+
+You will find here different ways to upgrade your wallabag:
+
+- `from 2.0.x to 2.1.1 <#upgrade-from-2-0-x-to-2-1-1>`_
+- `from 2.1.x to 2.1.y <#upgrading-from-2-1-x-to-2-1-y>`_
+- `from 1.x to 2.x <#from-wallabag-1-x>`_
+
 Upgrade from 2.0.x to 2.1.1
-===========================
+---------------------------
 
 .. warning::
 
     Before this migration, if you configured the Pocket import by adding your consumer key in Internal settings, please do a backup of it: you'll have to add it into the Config page after the upgrade.
 
 Upgrade on a dedicated web server
----------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ::
 
@@ -19,11 +28,11 @@ Upgrade on a dedicated web server
     php bin/console cache:clear --env=prod
 
 Upgrade on a shared hosting
----------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Backup your ``app/config/parameters.yml`` file.
 
-Download the last release of wallabag:
+Download the 2.1.1 release of wallabag:
 
 .. code-block:: bash
 
@@ -33,42 +42,7 @@ Download the last release of wallabag:
 
 Extract the archive in your wallabag folder and replace ``app/config/parameters.yml`` with yours.
 
-Please check that your ``app/config/parameters.yml`` contains all the required parameters. Here is a default ``parameters.yml`` file. If you don't know which parameter you need to set, please leave the default one.
-
-.. code-block:: yml
-
-    parameters:
-        database_driver: pdo_sqlite
-        database_host: 127.0.0.1
-        database_port: null
-        database_name: symfony
-        database_user: root
-        database_password: null
-        database_path: '%kernel.root_dir%/../data/db/wallabag.sqlite'
-        database_table_prefix: wallabag_
-        database_socket: null
-        mailer_transport: smtp
-        mailer_host: 127.0.0.1
-        mailer_user: null
-        mailer_password: null
-        locale: en
-        secret: ovmpmAWXRCabNlMgzlzFXDYmCFfzGv
-        twofactor_auth: true
-        twofactor_sender: no-reply@wallabag.org
-        fosuser_registration: true
-        fosuser_confirmation: true
-        from_email: no-reply@wallabag.org
-        rss_limit: 50
-        rabbitmq_host: localhost
-        rabbitmq_port: 5672
-        rabbitmq_user: guest
-        rabbitmq_password: guest
-        redis_scheme: tcp
-        redis_host: localhost
-        redis_port: 6379
-        redis_path: null
-
-You can find `here a documentation about parameters <http://doc.wallabag.org/en/master/user/parameters.html>`_.
+Please check that your ``app/config/parameters.yml`` contains all the required parameters. You can find `here a documentation about parameters <http://doc.wallabag.org/en/master/user/parameters.html>`_.
 
 If you use SQLite, you must also copy your ``data/`` folder inside the new installation.
 
@@ -85,3 +59,45 @@ You must run some SQL queries to upgrade your database. We assume that the table
     INSERT INTO `wallabag_craue_config_setting` (`name`, `value`, `section`) VALUES ('import_with_rabbitmq', '0', 'import');
     ALTER TABLE `wallabag_config` ADD `pocket_consumer_key` VARCHAR(255) DEFAULT NULL;
     DELETE FROM `wallabag_craue_config_setting` WHERE `name` = 'pocket_consumer_key';
+
+Upgrading from 2.1.x to 2.1.y
+-----------------------------
+
+Upgrade on a dedicated web server
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In order to upgrade your wallabag installation and get the last version, run the following command in you wallabag folder:
+
+::
+
+    make update
+
+Upgrade on a shared hosting
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Backup your ``app/config/parameters.yml`` file.
+
+Download the last release of wallabag:
+
+.. code-block:: bash
+
+    wget http://wllbg.org/latest-v2-package && tar xvf latest-v2-package
+
+You will find the `md5 hash of the latest package on our website <https://www.wallabag.org/pages/download-wallabag.html>`_.
+
+Extract the archive in your wallabag folder and replace ``app/config/parameters.yml`` with yours.
+
+Please check that your ``app/config/parameters.yml`` contains all the required parameters. You can find `here a documentation about parameters <http://doc.wallabag.org/en/master/user/parameters.html>`_.
+
+If you use SQLite, you must also copy your ``data/`` folder inside the new installation.
+
+Empty ``var/cache`` folder.
+
+From wallabag 1.x
+-----------------
+
+There is no automatic script to update from wallabag 1.x to wallabag 2.x. You need to:
+
+- export your data
+- install wallabag 2.x (`read the installation documentation <http://doc.wallabag.org/en/master/user/installation.html>`_ )
+- import data in this fresh installation (`read the import documentation <http://doc.wallabag.org/en/master/user/import.html>`_ )