diff --git a/docs/source/api.rst b/docs/source/api.rst
index 3481480fe..c0ef00a1e 100644
--- a/docs/source/api.rst
+++ b/docs/source/api.rst
@@ -1341,6 +1341,26 @@ Filter Warnings
 
 This example shows how to suppress the :class:`neo4j.ExperimentalWarning` using the :func:`python:warnings.filterwarnings` function.
 
+.. code-block:: python
+
+    import warnings
+    from neo4j import ExperimentalWarning
+
+    ...
+
+    with warnings.catch_warnings():
+        warnings.filterwarnings("ignore", category=ExperimentalWarning)
+        ...  # the call emitting the ExperimentalWarning
+
+    ...
+
+This will only mute the :class:`neo4j.ExperimentalWarning` for everything inside
+the ``with``-block. This is the preferred way to mute warnings, as warnings
+triggerd by new code will still be visible.
+
+However, should you want to mute it for the entire application, use the
+following code:
+
 .. code-block:: python
 
     import warnings
@@ -1348,6 +1368,8 @@ This example shows how to suppress the :class:`neo4j.ExperimentalWarning` using
 
     warnings.filterwarnings("ignore", category=ExperimentalWarning)
 
+    ...
+
 
 ********
 Bookmark