diff --git a/docs/conf.py b/docs/conf.py
index d85b9409e..65f72dfbc 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -42,6 +42,7 @@
     "sphinxcontrib.programoutput",
     "sphinx_github_changelog",
     "sphinx_copybutton",
+    "sphinxcontrib.mermaid",
     "procrastinate.contrib.sphinx",
 ]
 
@@ -98,6 +99,13 @@
 
 html_favicon = "favicon.ico"
 
+mermaid_init_js = """
+mermaid.initialize({
+    startOnLoad: true,
+    theme: "neutral"
+});
+"""
+
 # -- Options for sphinx.ext.autodoc ------------------------------------------
 
 autodoc_typehints = "both"
diff --git a/docs/discussions.md b/docs/discussions.md
index 16d6de502..b2202a96a 100644
--- a/docs/discussions.md
+++ b/docs/discussions.md
@@ -134,6 +134,41 @@ For a more practical approach, see {doc}`howto/advanced/locks`.
 
 (discussion-async)=
 
+## What are the different states of a Job and how do they go from one to another?
+
+A job can be in one of the following states:
+
+```{mermaid}
+flowchart LR
+    START:::hidden
+    todo[TODO]
+    doing[DOING]
+    succeeded[SUCCEEDED]
+    failed[FAILED]
+    cancelled[CANCELLED]
+    aborted[ABORTED]
+    START -- a --> todo
+    todo -- b --> doing
+    doing -- c --> succeeded
+    doing -- d --> todo
+    doing -- e --> failed
+    todo -- f --> cancelled
+    doing -- g --> aborted
+    classDef hidden display: none;
+```
+
+- **a**: The job was deferred by `my_task.defer()` (or the async equivalent)
+- **b**: A worker fetched the job from the database and started processing it
+- **c**: A worker finished processing a job successfully
+- **d**: The job failed by raising an error but will be retried
+- **e**: The job failed by raising an error and won't be retried
+- **f**: The job was cancelled by calling `job_manager.cancel_job_by_id(job_id)` (or the async equivalent) before its processing was started
+- **g**: The job was aborted during being processed by calling
+  `job_manager.cancel_job_by_id(job_id, abort=True)` (or the async equivalent). A sync job must also
+  handle the abort request by checking `context.should_abort()` and raising a
+  `JobAborted` exception. An async job handles it automatically by internally raising a
+  `CancelledError` exception.
+
 ## Asynchronous operations & concurrency
 
 Here, asynchronous (or async) means "using the Python `async/await` keywords, to
diff --git a/poetry.lock b/poetry.lock
index 83c155c1d..a5b49008e 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -1629,6 +1629,17 @@ files = [
 [package.extras]
 test = ["flake8", "mypy", "pytest"]
 
+[[package]]
+name = "sphinxcontrib-mermaid"
+version = "0.9.2"
+description = "Mermaid diagrams in yours Sphinx powered docs"
+optional = false
+python-versions = ">=3.7"
+files = [
+    {file = "sphinxcontrib-mermaid-0.9.2.tar.gz", hash = "sha256:252ef13dd23164b28f16d8b0205cf184b9d8e2b714a302274d9f59eb708e77af"},
+    {file = "sphinxcontrib_mermaid-0.9.2-py3-none-any.whl", hash = "sha256:6795a72037ca55e65663d2a2c1a043d636dc3d30d418e56dd6087d1459d98a5d"},
+]
+
 [[package]]
 name = "sphinxcontrib-programoutput"
 version = "0.17"
@@ -1887,4 +1898,4 @@ sqlalchemy = ["sqlalchemy"]
 [metadata]
 lock-version = "2.0"
 python-versions = "^3.8"
-content-hash = "e88d066984b0c6d684aa21f007b9eee8cb3c0fa48eb7f55d4a39b5598822e648"
+content-hash = "1b96e2c5ab73a198d5ec1f410cbd3f27d0fd28c5e3a7caac32c6567e76efb048"
diff --git a/pyproject.toml b/pyproject.toml
index c260f50e1..05b35b534 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -99,6 +99,7 @@ Sphinx = "*"
 sphinx-copybutton = "*"
 sphinx-github-changelog = "*"
 sphinxcontrib-programoutput = "*"
+sphinxcontrib-mermaid = "*"
 myst-parser = "*"
 
 [tool.poetry-dynamic-versioning]