diff --git a/pineappl_py/README.md b/pineappl_py/README.md
index b4ff694d..51d3668f 100644
--- a/pineappl_py/README.md
+++ b/pineappl_py/README.md
@@ -19,11 +19,20 @@ Run
 
 ```shell
 python -m venv env && . env/bin/activate
-pip install maturin
 ```
 
-to setup a new environment.
+to setup a new environment and check that `pip --version` returns at least `pip
+22.0 from ...`. If not, upgrade `pip` via
+
+```shell
+pip install -U pip
+```
 
+Next, install the needed dependencies:
+
+```shell
+pip install maturin
+```
 
 Run
 
@@ -31,13 +40,21 @@ Run
 maturin develop
 ```
 
-to build the project.
+to build the project, which also install it into the environment so that it can
+be used in Python project using the same environment.
 
-Run
+### Documentation
+
+Run the following once to install the documentation's dependencies:
+
+```shell
+pip install .[docs]
+```
+
+Then run
 
 ```shell
-maturin develop -E docs
-cd docs && make html
+( cd docs && make clean html )
 ```
 
 to generate the documentation.