diff --git a/swh/scheduler/celery_backend/pika_listener.py b/swh/scheduler/celery_backend/pika_listener.py
--- a/swh/scheduler/celery_backend/pika_listener.py
+++ b/swh/scheduler/celery_backend/pika_listener.py
@@ -1,8 +1,17 @@
-# Copyright (C) 2020  The Software Heritage developers
+# Copyright (C) 2020-2021  The Software Heritage developers
 # See the AUTHORS file at the top-level directory of this distribution
 # License: GNU General Public License version 3, or any later version
 # See top-level LICENSE file for more information
 
+"""This is the scheduler listener. It is in charge of listening to rabbitmq events (the
+task result) and flushes the "oneshot" tasks' status in the scheduler backend. It's the
+final step after a task is done.
+
+The scheduler runner :mod:`swh.scheduler.celery_backend.runner` is the module in charge
+of pushing tasks in the queue.
+
+"""
+
 import json
 import logging
 import sys
diff --git a/swh/scheduler/celery_backend/runner.py b/swh/scheduler/celery_backend/runner.py
--- a/swh/scheduler/celery_backend/runner.py
+++ b/swh/scheduler/celery_backend/runner.py
@@ -3,6 +3,15 @@
 # License: GNU General Public License version 3, or any later version
 # See top-level LICENSE file for more information
 
+"""This is the first scheduler runner. It is in charge of scheduling "oneshot" tasks
+(e.g save code now, indexer, vault, deposit, ...). To do this, it reads tasks ouf of the
+scheduler backend and pushes those to their associated rabbitmq queues.
+
+The scheduler listener :mod:`swh.scheduler.celery_backend.pika_listener` is the module
+in charge of finalizing the task results.
+
+"""
+
 import logging
 from typing import Dict, List, Tuple