feat(flutter): improve the debug symbol upload page (#15735)

<!-- Use this checklist to make sure your PR is ready for merge. You may
delete any sections you don't need. -->

## DESCRIBE YOUR PR

Makes the debug symbol upload page clearer for Dart and Flutter

## IS YOUR CHANGE URGENT?  

Help us prioritize incoming PRs by letting us know when the change needs
to go live.
- [ ] Urgent deadline (GA date, etc.): <!-- ENTER DATE HERE -->
- [ ] Other deadline: <!-- ENTER DATE HERE -->
- [x] None: Not urgent, can wait up to 1 week+

## SLA

- Teamwork makes the dream work, so please add a reviewer to your PRs.
- Please give the docs team up to 1 week to review your PR unless you've
added an urgent due date to it.
Thanks in advance for your help!

## PRE-MERGE CHECKLIST

*Make sure you've checked the following before merging your changes:*

- [ ] Checked Vercel preview for correctness, including links
- [ ] PR was reviewed and approved by any necessary SMEs (subject matter
experts)
- [ ] PR was reviewed and approved by a member of the [Sentry docs
team](https://github.com/orgs/getsentry/teams/docs)

## LEGAL BOILERPLATE

<!-- Sentry employees and contractors can delete or ignore this section.
-->

Look, I get it. The entity doing business as "Sentry" was incorporated
in the State of Delaware in 2015 as Functional Software, Inc. and is
gonna need some rights from me in order to utilize my contributions in
this here PR. So here's the deal: I retain all rights, title and
interest in and to my contributions, and by keeping this boilerplate
intact I confirm that Sentry can use, modify, copy, and redistribute my
contributions, under Sentry's choice of terms.

## EXTRA RESOURCES

- [Sentry Docs contributor guide](https://docs.sentry.io/contributing/)

Author: buenaflor

docs/platforms/dart/common/debug-symbols/dart-plugin.mdx

@@ -1,35 +1,9 @@
 ---
 title: Debug Symbols
-description: "Learn about uploading debug symbols to enable symbolication of stack traces in your Dart applications."
 sidebar_order: 3
 ---
 
-Debug symbols are essential for understanding stack traces in your Dart application when errors occur. Without debug symbols, stack traces from minified or obfuscated code can be difficult or impossible to interpret.
+Sentry currently does not support symbolication or debug symbol uploads for pure Dart applications. 
+This feature is being tracked in our GitHub issue: [sentry-dart/#1508](https://github.com/getsentry/sentry-dart/issues/1508).
 
-<Alert level="warning">
-
-Sentry currently doesn't support uploading debug symbols for pure Dart applications. Please see the [Flutter debug symbols documentation](/platforms/dart/guides/flutter/debug-symbols/) for Flutter applications. This feature is being tracked in our GitHub Issue: [sentry-dart/#1508](https://github.com/getsentry/sentry-dart/issues/1508).
-
-</Alert>
-
-## What Are Debug Symbols?
-
-Debug symbols provide the necessary information to convert program addresses back to function names, source file names, and line numbers. When you build a Dart application, especially with obfuscation or optimization enabled, this information is typically removed from the main application bundle to reduce size.
-
-## When to Upload Debug Symbols
-
-With default settings, complete stack traces are available in your Dart errors out of the box, unless you use [`split-debug-info`](https://flutter.dev/docs/perf/app-size#reducing-app-size) and [`obfuscate`](https://flutter.dev/docs/deployment/obfuscate) flags. In these cases, you must upload the debug information files generated by the build, so Sentry can show proper stack traces.
-
-## Upload Methods
-
-Sentry offers several methods to upload debug symbols for Dart applications:
-
-1. **[Sentry Dart Plugin (Recommended)](/platforms/dart/debug-symbols/dart-plugin)** - The easiest way to automatically upload debug symbols for iOS, Android, Desktop and Web.
-
-2. **[Manual Upload Options](/platforms/dart/debug-symbols/manual-upload):**
-   - [iOS and macOS](/platforms/apple/dsym/) - Upload dSYM files for symbolication of Apple platform crashes.
-   - [Android](/cli/dif/#uploading-files) - Upload mapping files manually using the Sentry CLI.
-   - [Android NDK](/cli/dif/#uploading-files) - Upload ELF DWARF debug files for native code crashes.
-   - [Web](/cli/releases/#upload-source-maps) - Upload source maps for Flutter web applications.
-
-Choose the method that best suits your workflow and platform requirements. For most users, the Sentry Dart Plugin provides the simplest solution across all platforms. 
+See the [Flutter debug symbols documentation](/platforms/dart/guides/flutter/debug-symbols/) for Flutter applications. 

docs/platforms/dart/common/debug-symbols/index.mdx

@@ -1,9 +1,9 @@
 ---
 title: Sentry Dart Plugin
-description: "Learn how to use the Sentry Dart Plugin to automatically upload debug symbols for your Dart application."
+description: "Learn how to use the Sentry Dart Plugin to automatically upload debug symbols for your Flutter application."
 sidebar_order: 1
 ---
 
-The [Sentry Dart Plugin](https://github.com/getsentry/sentry-dart-plugin) is the recommended way to upload debug symbols for Dart applications. It automates the upload process for Android, iOS, macOS, and Web, making it seamless to provide Sentry with the necessary files for symbolication.
+The [Sentry Dart Plugin](https://github.com/getsentry/sentry-dart-plugin) is the recommended way to upload debug symbols for Flutter applications. It automates the upload process for Android, iOS, macOS, and Web, making it seamless to provide Sentry with the necessary files for symbolication.
 
 <PlatformContent includePath="debug-symbols/dart-plugin" /> 

docs/platforms/dart/common/debug-symbols/manual-upload.mdx

@@ -1,29 +1,23 @@
 ---
 title: Debug Symbols
-description: "Learn about uploading debug symbols to enable symbolication of stack traces in your Dart applications."
+description: "Learn about uploading debug symbols to enable symbolication of stack traces in your Flutter applications."
 sidebar_order: 3
 ---
 
-Debug symbols are essential for understanding stack traces in your Dart application when errors occur. Without debug symbols, stack traces from minified or obfuscated code can be difficult or impossible to interpret.
+Debug symbols are essential for understanding stack traces in your Flutter application when errors occur. Without debug symbols, stack traces from minified or obfuscated code can be difficult or impossible to interpret.
 
 ## What Are Debug Symbols?
 
-Debug symbols provide the necessary information to convert program addresses back to function names, source file names, and line numbers. When you build a Dart application, especially with obfuscation or optimization enabled, this information is typically removed from the main application bundle to reduce size.
+Debug symbols provide the necessary information to convert program addresses back to function names, source file names, and line numbers. When you build a Flutter application, especially with obfuscation or optimization enabled, this information is typically removed from the main application bundle to reduce size.
 
 ## When to Upload Debug Symbols
 
-With default settings, complete stack traces are available in your Dart errors out of the box, unless you use [`split-debug-info`](https://flutter.dev/docs/perf/app-size#reducing-app-size) and [`obfuscate`](https://flutter.dev/docs/deployment/obfuscate) flags. In these cases, you must upload the debug information files generated by the build, so Sentry can show proper stack traces.
+With default settings, complete stack traces are available in your Flutter errors out of the box, unless you use [`split-debug-info`](https://flutter.dev/docs/perf/app-size#reducing-app-size) and [`obfuscate`](https://flutter.dev/docs/deployment/obfuscate) flags. In these cases, you must upload the debug information files generated by the build, so Sentry can show proper stack traces.
 
 ## Upload Methods
 
-Sentry offers several methods to upload debug symbols for Dart applications:
+Sentry offers several methods to upload debug symbols for Flutter applications:
 
-1. **[Sentry Dart Plugin (Recommended)](/platforms/dart/guides/flutter/debug-symbols/dart-plugin)** - The easiest way to automatically upload debug symbols for iOS, Android, and Web.
+1. **[Sentry Dart Plugin (Recommended)](/platforms/dart/guides/flutter/debug-symbols/dart-plugin)** - The easiest and most reliable way to upload debug symbols for Flutter applications. It automatically processes, filters, and uploads the correct symbol files for iOS, Android, and Web - significantly reducing the chances of misconfiguration.
 
-2. **[Manual Upload Options](/platforms/dart/guides/flutter/debug-symbols/manual-upload):**
-   - [iOS and macOS](/platforms/apple/dsym/) - Upload dSYM files for symbolication of Apple platform crashes.
-   - [Android](/cli/dif/#uploading-files) - Upload mapping files manually using the Sentry CLI.
-   - [Android NDK](/cli/dif/#uploading-files) - Upload ELF DWARF debug files for native code crashes.
-   - [Web](/cli/releases/#upload-source-maps) - Upload source maps for Flutter web applications.
-
-Choose the method that best suits your workflow and platform requirements. For most users, the Sentry Dart Plugin provides the simplest solution across all platforms. 
+2. **[Manual Upload Options](/platforms/dart/guides/flutter/debug-symbols/manual-upload)** - Because this method is more complex, requires additional manual steps, and is not currently documented, we do not recommend using it unless absolutely necessary.

docs/platforms/dart/guides/flutter/debug-symbols/dart-plugin.mdx

@@ -1,9 +1,9 @@
 ---
 title: Manual Upload
-description: "Learn how to manually upload debug symbols for your Dart applications."
+description: "Learn how to manually upload debug symbols for your Flutter applications."
 sidebar_order: 2
 ---
 
-If you choose not to use the Sentry Dart Plugin, you can manually upload debug symbols for your Dart applications. This page provides instructions for different platforms.
+If you choose not to use the Sentry Dart Plugin, you can manually upload debug symbols for your Flutter applications. This page provides instructions for different platforms.
 
 <PlatformContent includePath="debug-symbols/manual-upload" /> 

docs/platforms/dart/guides/flutter/debug-symbols/index.mdx

@@ -39,6 +39,14 @@ sentry:
   # ___PRODUCT_OPTION_END___ source-maps
 ```
 
+<OnboardingOption optionId="source-context">
+<Alert>
+For iOS and Android builds, source context is only supported if you build the Flutter app using the `--split-debug-info` flag.
+
+Additionally source context currently only covers code in the main app package. For example, if your main app package depends on an internal package or a third-party package and an error occurs in that dependency, its source context will not be shown.
+</Alert>
+</OnboardingOption>
+
 <OnboardingOption optionId="dsym">
 The `upload_debug_symbols` option defaults to `true` when not specified.
 </OnboardingOption>