diff --git a/docs/platforms/python/tracing/instrumentation/custom-instrumentation/index.mdx b/docs/platforms/python/tracing/instrumentation/custom-instrumentation/index.mdx
index b92783fec5c02..60a51e3c2fa66 100644
--- a/docs/platforms/python/tracing/instrumentation/custom-instrumentation/index.mdx
+++ b/docs/platforms/python/tracing/instrumentation/custom-instrumentation/index.mdx
@@ -56,6 +56,12 @@ def eat_pizza(pizza):
                 eat_slice(pizza.slices.pop())
 ```
 
+<Alert title="Changed in 2.15.0" level="info">
+
+The parameter `name` in `start_span()` used to be called `description`. In version 2.15.0 `description` was deprecated and from 2.15.0 on, only `name` should be used. `description` will be removed in `3.0.0`.
+
+</Alert>
+
 ### Using a Decorator
 
 ```python
@@ -88,10 +94,16 @@ def eat_slice(slice):
 def eat_pizza(pizza):
     with sentry_sdk.start_transaction(op="task", name="Eat Pizza"):
         while pizza.slices > 0:
-            span = sentry_sdk.start_span(description="Eat Slice")
+            span = sentry_sdk.start_span(name="Eat Slice")
             eat_slice(pizza.slices.pop())
             span.finish()
 ```
+<Alert title="Changed in 2.15.0" level="info">
+
+The parameter `name` in `start_span()` used to be called `description`. In version 2.15.0 `description` was deprecated and from 2.15.0 on, only `name` should be used. `description` will be removed in `3.0.0`.
+
+</Alert>
+
 
 When you create your span manually, make sure to call `span.finish()` after the block of code you want to wrap in a span to finish the span. If you do not finish the span it will not be sent to Sentry.
 
@@ -113,6 +125,13 @@ def eat_slice(slice):
             chew()
 ```
 
+<Alert title="Changed in 2.15.0" level="info">
+
+The parameter `name` in `start_span()` used to be called `description`. In version 2.15.0 `description` was deprecated and from 2.15.0 on, only `name` should be used. `description` will be removed in `3.0.0`.
+
+</Alert>
+
+
 ### Using a Decorator
 
 ```python
@@ -136,15 +155,21 @@ def chew():
     ...
 
 def eat_slice(slice):
-    parent_span = sentry_sdk.start_span(description="Eat Slice")
+    parent_span = sentry_sdk.start_span(name="Eat Slice")
 
-    child_span = parent_span.start_child(description="Chew")
+    child_span = parent_span.start_child(name="Chew")
     chew()
     child_span.finish()
 
     parent_span.finish()
 ```
 
+<Alert title="Changed in 2.15.0" level="info">
+
+The parameter `name` in `start_span()` used to be called `description`. In version 2.15.0 `description` was deprecated and from 2.15.0 on, only `name` should be used. `description` will be removed in `3.0.0`.
+
+</Alert>
+
 The parameters of `start_span()` and `start_child()` are the same. See the [API reference](https://getsentry.github.io/sentry-python/api.html#sentry_sdk.api.start_span) for more details.
 
 When you create your span manually, make sure to call `span.finish()` after the block of code you want to wrap in a span to finish the span. If you do not finish the span it will not be sent to Sentry.