diff --git a/src/BUILD b/src/BUILD
index 43394098..ddf506de 100644
--- a/src/BUILD
+++ b/src/BUILD
@@ -53,11 +53,11 @@ py_library(
     visibility = ["//visibility:public"],
 )
 
-# In order to update the requirements, change the `requirements.txt` file and run:
-# `bazel run //src:requirements`.
-# This will update the `requirements_lock.txt` file.
+# In order to update the requirements, change the `requirements.in` file and run:
+# `bazel run //src:requirements.update`.
+# This will update the `requirements.txt` file.
 # To upgrade all dependencies to their latest versions, run:
-# `bazel run //src:requirements -- --upgrade`.
+# `bazel run //src:requirements.update -- --upgrade`.
 compile_pip_requirements(
     name = "requirements",
     srcs = [
diff --git a/src/README.md b/src/README.md
index 2a0ba8a6..e84f9279 100644
--- a/src/README.md
+++ b/src/README.md
@@ -80,6 +80,23 @@ Find everything related to testing and how to add your on test suite [here](/too
 
 > If you want to develop your own sphinx extension, check out the [extensions guide](/src/extensions/README.md)
 
+## Updating dependencies
+
+The file [requirements.in](./requirements.in) is a [PIP requirements file](https://pip.pypa.io/en/stable/reference/requirements-file-format/) that describe first level dependencies.
+
+The file [requirements.txt](./requirements.txt) is a [pip-compile lock file](https://pip-tools.readthedocs.io/en/latest/cli/pip-compile/) that holds
+the pinned dependency tree calculated from [requirements.in](./requirements.in).
+
+To update dependencies (e.g. after adding a dependency), run:
+```
+bazel run //src:requirements.update
+```
+
+To update the full dependency tree, run
+```
+bazel run //src:requirements.update -- --upgrade
+```
+
 ## Best Practices
 
 1. **Documentation**