diff --git a/README.md b/README.md
deleted file mode 100644
index 6104b9fa4020fda3db25edc53457d907133dfa87..0000000000000000000000000000000000000000
--- a/README.md
+++ /dev/null
@@ -1,43 +0,0 @@
-# Batmen
-
-Batmen is a plugin to the scientific simulator [Batsim].
-It allows simulating users of large-scale distributed systems.
-Batmen is originally a fork of [batsched].
-
-## How does it work?
-
-
-
-A simulation with [Batsim] consists of two processes:
-- Batsim itself, in charge of reading an input workload and **simulating the platform** (job arrival, job termination, energy consumed...)
-- a scheduler, in charge of **making the scheduling decisions**. The scheduler communicates with Batsim via a ZeroMQ socket through messages defined in [Batsim protocol](https://batsim.readthedocs.io/en/latest/protocol.html).
-
-In Batmen, we added a layer: **the simulation of users**.
-
-### User simulation
-The interaction with users happens through a "broker". The broker manages a pool of simulated users and dynamically register new jobs to submit. These jobs come on top of the input workload read by Batsim.
-
-Implementation, in the folder `src/users`:
-- class `Broker`: implement the broker, submitting the jobs on behalf of the users
-- class `DynScheduler`: superclass managing the interaction with the broker from the scheduler
-- class `User`: an individual user, submitting her jobs to the broker
-
-### Types of user
-
-For now, we have developed three types of users.
-
-- *modeled users* (class `User`): using a model to generate the jobs to submit
-- *replay users* (class `ReplayUser`): replaying a workload trace given as input
-- *feedback users* (class `FeedbackUser`): taking feedback on the status of previous jobs into account when submitting the next one
-
-
-
-
-
-
-
-
-[Nix]: https://nixos.org/nix/
-[Batsim]: https://batsim.org/
-[batsched]: https://framagit.org/batsim/batsched
-[Batmen doc]: https://batmen.readthedocs.io/en/latest/
\ No newline at end of file
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000000000000000000000000000000000000..8ac86a14642d6e53cf6b643b28b0b1f443eb9521
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,34 @@
+Batmen
+======
+
+Batmen is a plugin to the scientific simulator `Batsim <https://batsim.org/>`_.
+It allows the simulation of **users** (bat-men) of large-scale distributed systems.
+Batmen is originally a fork of `batsched <https://framagit.org/batsim/batsched>`_.
+
+How does is work?
+-----------------
+
+.. image:: ./batmen_diagram.svg
+ :alt: Batmen diagram
+
+A simulation with Batmen has to be launched in parallel with Batsim.
+
+* Batsim takes care of **simulating the IT platform** (job arrival, job termination, energy consumed...), thanks to the underlying simulator `SimGrid <https://simgrid.org/>`_.
+* Batmen simulates the **users of the system**, through their **job submission behavior**. It also simulates the **scheduler**.
+
+Documentation
+-------------
+For more information, refer to `Batmen documentation <https://batmen.readthedocs.io>`_.
+
+
+Aknowledgments
+--------------
+Batmen was developped mainly by Maël Madon during his PhD thesis.
+The most up-to-date description can be found in Chapter II of the `thesis manuscript <https://cloud.irit.fr/s/ZjafxKO0YnaMqpK>`_ (and more precisely in Section II.2.2).
+It was used to carry scientific experimental campains, leading to several peer-reveiwed publications:
+
+* `Europar'22 <https://doi.org/10.1007/978-3-031-12597-3_4>`_: Maël Madon, Georges Da Costa, and Jean-Marc Pierson. *"Characterization of Different User Behaviors for Demand Response in Data Centers"*
+* `FGCS'24 <https://doi.org/10.1016/j.future.2024.01.024>`_: Maël Madon, Georges Da Costa, and Jean-Marc Pierson. *"Replay with Feedback: How Does the Performance of HPC System Impact User Submission Behavior?"*
+* ICT4S'24: Jolyne Gatt, Maël Madon, and Georges Da Costa. *"Digital Sufficiency Behaviors to Deal with Intermittent Energy Sources in a Data Center"*
+
+If you use Batmen for your work, please cite one of these.
\ No newline at end of file
diff --git a/docs/dev/user_simu.md b/docs/dev/user_simu.md
new file mode 100644
index 0000000000000000000000000000000000000000..1e61a4345fcf908cd69192ef49276f07901d5d0e
--- /dev/null
+++ b/docs/dev/user_simu.md
@@ -0,0 +1,18 @@
+# User simulation
+The interaction with users happens through a "broker".
+The broker manages a pool of simulated users and dynamically register new jobs to submit.
+These jobs come on top of the input workload read by Batsim.
+
+Implementation, in the folder `src/users`:
+
+- class `Broker`: implement the broker, submitting the jobs on behalf of the users
+- class `DynScheduler`: superclass managing the interaction with the broker from the scheduler
+- class `User`: an individual user, submitting her jobs to the broker
+
+## Types of user
+
+For now, we have developed three types of users.
+
+- *modeled users* (class `User`): using a model to generate the jobs to submit
+- *replay users* (class `ReplayUser`): replaying a workload trace given as input
+- *feedback users* (class `FeedbackUser`): taking feedback on the status of previous jobs into account when submitting the next one
diff --git a/docs/index.rst b/docs/index.rst
index 222bb20faedad8f64715387e52cded279f930d84..178c5ae82e22eadd67386e9485a1d79d02226833 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -8,6 +8,7 @@ Welcome to Batmen's documentation!
Batmen is a plugin to the scientific simulator `Batsim <https://batsim.org/>`_.
It allows the simulation of **users** (bat-men) of large-scale distributed systems.
+Batmen is originally a fork of `batsched <https://framagit.org/batsim/batsched>`_.
How does is work?
-----------------
@@ -21,21 +22,21 @@ A simulation with Batmen has to be launched in parallel with Batsim.
* Batmen simulates the **users of the system**, through their **job submission behavior**. It also simulates the **scheduler**.
Batmen was developped mainly by Maël Madon during his PhD thesis.
-The most up-to-date description can be found in Chapter II of the thesis manuscript (and more precisely in Section II.2.2).
+The most up-to-date description can be found in Chapter II of the `thesis manuscript <https://cloud.irit.fr/s/ZjafxKO0YnaMqpK>`_ (and more precisely in Section II.2.2).
It was used to carry scientific experimental campains, leading to several peer-reveiwed publications:
* `Europar'22 <https://doi.org/10.1007/978-3-031-12597-3_4>`_: Maël Madon, Georges Da Costa, and Jean-Marc Pierson. *"Characterization of Different User Behaviors for Demand Response in Data Centers"*
* `FGCS'24 <https://doi.org/10.1016/j.future.2024.01.024>`_: Maël Madon, Georges Da Costa, and Jean-Marc Pierson. *"Replay with Feedback: How Does the Performance of HPC System Impact User Submission Behavior?"*
* ICT4S'24: Jolyne Gatt, Maël Madon, and Georges Da Costa. *"Digital Sufficiency Behaviors to Deal with Intermittent Energy Sources in a Data Center"*
-If you use it for your work, please cite one of these.
+If you use Batmen for your work, please cite one of these.
-This documentation is divided in two parts, user and developer manual:
+This present documentation is divided in two parts, user and developer manual:
.. toctree::
:maxdepth: 1
- :caption: User manual:
+ :caption: User manual
user/installation.md
user/first_simu.md
@@ -44,8 +45,9 @@ This documentation is divided in two parts, user and developer manual:
.. toctree::
:maxdepth: 1
- :caption: Developer manual:
+ :caption: Developer manual
+ dev/user_simu.md
+ dev/scheduler.md
dev/tests.md
- dev/documentation.md
- dev/scheduler.md
\ No newline at end of file
+ dev/documentation.md
\ No newline at end of file