feat(sourcemaps): Add more sourcemaps docs

src/platform-includes/sourcemaps/artifact-and-release-bundles/javascript.mdx

@@ -0,0 +1,63 @@
+This article explains the differences between Artifact and Release Bundles, and the implications of using them. Visit [Uploading Source Maps](/platforms/javascript/guides/react/sourcemaps/uploading/) if you're looking for our guides on how to upload source maps.
+
+## Introduction
+
+Sentry currently supports two methods of uploading sourcemaps: **Release Bundles** and **Artifact Bundles**. A bundle, at a higher level, contains all the minified sources and source maps (known as _artifacts_) required for Sentry to unminify the frames of a stack trace.
+
+## Release Bundles
+
+### What Are They?
+
+A release bundle is a bundle format that is connected to an existing `release` in Sentry. For this reason **the creation of a `release` is required** before uploading your artifacts.
+
+| Pros | Cons |
+|:--|:--|
+| Works with every SDK version | Configuring your build pipeline to upload artifacts can be very challenging  |
+| | Requires your project to use Sentry Releases
+
+### How Do They Work?
+
+```
+Diagram Here
+```
+
+Release Bundles are called like that because they use a `release` as way to index a specific bundle*. The `release` is extracted from the incoming error and used to lookup the most recent bundle. When a bundle is found, we use the absolute path in each frame to find the corresponding minified source in the retrieved bundle. Once the minified source is found, we try to discover its source map with a series of heuristics (e.g., looking at the `sourceURLMapping` comment, using metadata from the uploaded bundle).
+
+In practice, matching the paths for artifacts discovery is prone to mistmatchs that might be caused by a wrong configuration of your bundler, CI/CD pipeline...
+
+## Artifact Bundles
+
+### What Are They?
+
+An artifact bundle is our new bundle format that aims to address the shortcomings of release bundles by **adding the support for Debug IDs** and **removing the need to create a `release`**.
+
+| Pros | Cons |
+|:--|:--|
+| With the use of Debug IDs, configuring your build pipeline to upload artifacts is trivial | Requires a version update to Javascript SDKs, bundler plugin ( and `sentry-cli`) |
+| Associating a release is still possible, but not required | May cause problems with integrity checks
+
+### How Do They Work?
+
+```
+Diagram Here
+```
+
+Artifact Bundles solve the challenge of matching paths by using a new identification mechanism known as Debug IDs. Rather than relying on paths we uniquely identify and bind pairs of minified sources and source maps with an Debug ID(UUID). With this, we are able to quickly identify the minified source and corresponding source map without ever needing to check any paths. Thus, you don't have to worry about wrong paths configurations.
+
+<Note>
+
+If you want to learn more about the rationale behind Debug IDs, we suggest taking a look at our [engineering blog](https://sentry.engineering/blog/the-case-for-debug-ids).
+
+</Note>
+
+### Associating a Release with Artifact Bundles
+
+Since you might still want to know to which release a specific artifact bundle is connected to, we designed a new way to still associate a `release` to your bundle.
+
+The new Artifact Bundle format supports a new kind of association to a `release` and optionally `dist`, known as weak release association. This type of association **will not require the creation of a `release`** before uploading sourcemaps and will consequentely allow the creation of a `release` as a separate step down the pipeline.
+
+With an associated `release` and optionally `dist` you will be able to quickly go to the Artifact Bundle from your `release` in Sentry, without having to worry about which artifact bundle was used for your errors.
+
+## Summary
+- We recommend you try Artifact Bundles with Debug IDs, if you've failed to upload source maps in the past.
+- However, we recommend you continue to use Release Bundles if your application already uses them successfully.

src/platform-includes/sourcemaps/upload/cli/javascript.mdx

@@ -49,9 +49,7 @@ Uploading artifact bundles requires:
 
 </Note>
 
-If you decide to upload as an artifact bundle you should use Debug IDs. Debug IDs are unique identifiers generated by the `sentry-cli` that bind together minified sources and their respective source maps. Each pair of `(minified source, source map)` contain the same Debug ID, which is injected into specific parts of each file.
-
-The generated Debug IDs are used by Sentry during processing to determine which source map file should be used to symbolicate an event's stackframes.
+If you decide to upload as an artifact bundle you should use Debug IDs, which are described more in detail in [artifact bundles vs. release bundles](ADD LINK).
 
 <Note>
 
@@ -81,7 +79,7 @@ module.exports = {
 
 ### 2. Inject Debug IDs Into Artifacts
 
-During injection, `sentry-cli` will evaluate all minified sources and respective source maps (known as build artifacts), adding the Debug IDs required to correctly symbolicate an event.
+During injection, `sentry-cli` will evaluate all minified sources and respective source maps (known as build artifacts), adding the Debug IDs required to correctly unminify an event.
 
 To inject Debug IDs, use the new `inject` command:
 
@@ -129,7 +127,7 @@ Open up Sentry and navigate to **Project Settings > Source Maps**. If you choose
 
 #### Associating `release` with Artifact Bundle (Optional)
 
-If you are having troubles with Debug IDs, we suggest that you associate a release to an artifact bundle. _The release association will help Sentry figure out which artifact bundle(s) to use for symbolication when Debug IDs are not present._
+If you are having troubles with Debug IDs, we suggest that you associate a release to an artifact bundle. _The release association will help Sentry figure out which artifact bundle(s) to use for unminification when Debug IDs are not present._
 
 First, you must provide a `release` property in your SDK options.
 
@@ -177,7 +175,7 @@ Sentry can also use [releases](/product/releases/) to match uploaded source maps
 
 <Note>
 
-We strongly suggest to use the new Debug IDs system for uploading your artifacts since it provides more reliable symbolication and the old release-based system will be faded out in the future.
+We strongly suggest to use the new Debug IDs system for uploading your artifacts since it provides more reliable unminification and the old release-based system will be faded out in the future.
 
 </Note>
 

src/platforms/javascript/common/sourcemaps/artifact-and-release-bundles.mdx

@@ -0,0 +1,7 @@
+---
+title: Artifact vs. Release Bundles
+description: "Learn about the differences between artifact bundles and release bundles."
+sidebar_order: 6
+---
+
+<PlatformContent includePath="sourcemaps/artifact-and-release-bundles" />

src/platforms/javascript/common/sourcemaps/best-practices.mdx

@@ -1,7 +1,7 @@
 ---
 title: Best Practices
 description: "Learn about best practices when integrating your source maps with Sentry."
-sidebar_order: 7
+sidebar_order: 4
 notSupported:
   - javascript.nextjs
   - javascript.remix

src/platforms/javascript/common/sourcemaps/troubleshooting_js.mdx

@@ -3,7 +3,7 @@ title: Troubleshooting Source Maps
 redirect_from:
   - /platforms/javascript/sourcemaps/troubleshooting/
 description: "Troubleshooting for source maps."
-sidebar_order: 8
+sidebar_order: 5
 ---
 
 <PlatformContent includePath="sourcemaps/troubleshooting" />

src/platforms/javascript/common/sourcemaps/uploading/index.mdx

@@ -1,7 +1,7 @@
 ---
 title: Uploading Source Maps
 description: "Learn how to provide your source maps to Sentry."
-sidebar_order: 3
+sidebar_order: 2
 notSupported:
   - javascript.nextjs
   - javascript.remix

src/platforms/javascript/common/sourcemaps/validating.mdx

@@ -1,7 +1,7 @@
 ---
 title: Validating Files
 description: "Learn about Sentry's online validation tool that can be used to test your source maps against your hosted source."
-sidebar_order: 6
+sidebar_order: 3
 ---
 
 <PlatformContent includePath="sourcemaps/validating" />