diff --git a/README.rst b/README.rst
index b5a532c38fe612610f390ad2d1f6fd0415eb92db..efcbffaf1a69baeb181cde8c7e4932bf1fa0eb80 100644
--- a/README.rst
+++ b/README.rst
@@ -26,18 +26,8 @@ BEAT_ packages through Gitlab and conda_.
 Installation
 ------------
 
-You can install this package via conda_, simply pointing to our stable or beta
-channels::
-
-  $ conda create -n bdt -c https://www.idiap.ch/software/bob/conda bob.devtools
-  # or, for beta releases:
-  $ conda create -n bdt -c https://www.idiap.ch/software/bob/conda/label/beta bob.devtools
-
-We provide packages for both 64-bit Linux and MacOS. Once installed, you can
-use these tools within the created environment like this::
-
-  $ conda activate bdt
-  (bdt) $ bdt --help
+For most up-to-date installation and usage instructions, consult the
+installation section at the `user guide`_.
 
 
 Contact
@@ -52,3 +42,4 @@ development `mailing list`_.
 .. _bob: https://www.idiap.ch/software/bob
 .. _beat: https://www.idiap.ch/software/beat
 .. _mailing list: https://www.idiap.ch/software/bob/discuss
+.. _user guide: https://www.idiap.ch/software/bob/docs/bob/bob.devtools/master/install.html
diff --git a/doc/index.rst b/doc/index.rst
index c99f0a5fa85e5c3cb149c0ed09a8f19e750f33e7..85f0cdedb566aeef35393dcbca57d873e00628ce 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -15,6 +15,7 @@ Documentation
 .. toctree::
    :maxdepth: 2
 
+   install
    release
    api
    ci
diff --git a/doc/install.rst b/doc/install.rst
new file mode 100644
index 0000000000000000000000000000000000000000..e6e35897534220c36199cb90eff6bffc31249dd8
--- /dev/null
+++ b/doc/install.rst
@@ -0,0 +1,52 @@
+.. vim: set fileencoding=utf-8 :
+
+.. _bob.devtools.install:
+
+
+==============
+ Installation
+==============
+
+You can install this package via conda_, simply pointing to our stable or beta
+channels::
+
+  $ conda create -n bdt -c https://www.idiap.ch/software/bob/conda bob.devtools
+  # or, for beta releases:
+  $ conda create -n bdt -c https://www.idiap.ch/software/bob/conda/label/beta bob.devtools
+
+We provide packages for both 64-bit Linux and MacOS.  Once installed, you can
+use these tools within the created environment like this::
+
+  $ conda activate bdt
+  (bdt) $ bdt --help
+
+
+
+Setup
+=====
+
+Some of the commands in the ``bdt`` command-line application require access to
+your gitlab private token, which you can pass at every iteration, or setup at
+your ``~/.python-gitlab.cfg``.  Please note that in case you don't set it up,
+it will request for your API token on-the-fly, what can be cumbersome and
+repeatitive.  Your ``~/.python-gitlab.cfg`` should roughly look like this
+(there must be an "idiap" section on it, at least):
+
+.. code-block:: ini
+
+   [global]
+   default = idiap
+   ssl_verify = true
+   timeout = 15
+
+   [idiap]
+   url = https://gitlab.idiap.ch
+   private_token = <obtain token at your settings page in gitlab>
+   api_version = 4
+
+We recommend you set ``chmod 600`` to this file to avoid prying us to read out
+your personal token. Once you have your token set up, communication should work
+transparently between these gitlab clients and the server.
+
+
+.. include:: links.rst
diff --git a/doc/links.rst b/doc/links.rst
index 7e2f8a143104e5a3323cc0cdabb8bf28f2fff525..7b1d52e57891159796b33049a6daa97198ade273 100644
--- a/doc/links.rst
+++ b/doc/links.rst
@@ -2,6 +2,7 @@
 
 .. Place here references to all citations in lower case
 
+.. _conda: https://conda.io
 .. _bob: https://www.idiap.ch/software/bob
 .. _shell executor: https://docs.gitlab.com/runner/executors/shell.html
 .. _gitlab runner: https://docs.gitlab.com/runner/install/osx.html
diff --git a/doc/release.rst b/doc/release.rst
index edeabada37bc948ac51340930d32ab609e996a89..7130bc5296224c1a0eadbbf990e2a30808e1aa6d 100644
--- a/doc/release.rst
+++ b/doc/release.rst
@@ -14,32 +14,6 @@ with each release.  The changelog can be autogenerated from merge-requests or
 commits in the target package.
 
 
-Setup
-=====
-
-These programs require access to your gitlab private token which you can pass
-at every iteration or setup at your ``~/.python-gitlab.cfg``. If you don't set
-it up, it will request for your API token on-the-fly, what can be cumbersome
-and repeatitive. Your ``~/.python-gitlab.cfg`` should roughly look like this
-(there must be an "idiap" section on it, at least):
-
-.. code-block:: ini
-
-   [global]
-   default = idiap
-   ssl_verify = true
-   timeout = 15
-
-   [idiap]
-   url = https://gitlab.idiap.ch
-   private_token = <obtain token at your settings page in gitlab>
-   api_version = 4
-
-We recommend you set ``chmod 600`` to this file to avoid prying us to read out
-your personal token. Once you have your token set up, communication should work
-transparently between these gitlab clients and the server.
-
-
 Usage
 =====