feat(python): Clarification regarding start_transaction (#12835)

Author: sentrivana

docs/platforms/python/tracing/instrumentation/custom-instrumentation/index.mdx

@@ -3,7 +3,7 @@ title: Custom Instrumentation
 description: "Learn how to capture performance data on any action in your app."
 ---
 
-The Sentry SDK for Python does a very good job of auto instrumenting your application. If you use one of the popular frameworks, we've got you covered because well-known operations like HTTP calls and database queries will be instrumented out of the box. The Sentry SDK will also check your installed Python packages and auto enable the matching SDK integrations. If you want to enable tracing in a piece of code that performs some other operations, add the @sentry_sdk.trace decorator"
+The Sentry SDK for Python does a very good job of auto instrumenting your application. If you use one of the popular frameworks, we've got you covered because well-known operations like HTTP calls and database queries will be instrumented out of the box. The Sentry SDK will also check your installed Python packages and auto-enable the matching SDK integrations. If you want to enable tracing in a piece of code that performs some other operations, add the `@sentry_sdk.trace` decorator.
 
 ## Add a Transaction
 
@@ -31,6 +31,12 @@ def eat_pizza(pizza):
 
 The [API reference](https://getsentry.github.io/sentry-python/api.html#sentry_sdk.api.start_transaction) documents `start_transaction` and all its parameters.
 
+<Alert>
+
+Note that `sentry_sdk.start_transaction()` is meant be used as a context manager. This ensures that the transaction will be properly set as active and any spans created within will be attached to it.
+
+</Alert>
+
 ## Add Spans to a Transaction
 
 If you want to have more fine-grained performance monitoring, you can add child spans to your transaction, which can be done by either:
@@ -39,7 +45,7 @@ If you want to have more fine-grained performance monitoring, you can add child
 - Using a decorator (this works on sync and async functions)
 - Manually starting and finishing a span
 
-Calling a `sentry_sdk.start_span()` will find the current active transaction and attach the span to it.
+Calling `sentry_sdk.start_span()` will find the current active transaction and attach the span to it.
 
 ### Using a Context Manager
 

platform-includes/distributed-tracing/custom-instrumentation/python.mdx

@@ -20,7 +20,7 @@ headers = get_incoming_headers_as_dict()
 
 transaction = sentry_sdk.continue_trace(headers)
 with sentry_sdk.start_transaction(transaction):
-   ...
+    ...
 ```
 
 In this example, `get_incoming_headers_as_dict()` returns a dictionary that contains tracing information from HTTP headers, environment variables, or any other mechanism your project uses to communicate with the outside world.