address most PR comments

c298lee · c298lee · commit e1f79800bfbd · 2024-12-13T15:04:46.000-05:00
diff --git a/docs/product/dev-toolbar/index.mdx b/docs/product/dev-toolbar/index.mdx
@@ -9,44 +9,44 @@ description: "Bring critical Sentry insights and tools directly into your web ap
   [GitHub](https://github.com/getsentry/sentry-toolbar/issues) if you have any feedback or concerns.
 </Alert>
 
-Developers spend a lot of time troubleshooting their web apps on local, staging, and production environments. The Sentry Dev Toolbar pulls data from [sentry.io](http://sentry.io) and surfaces relevant actionable issues to you when you have the most context for understanding it: as you browse your own site. The Dev Toolbar is a floating widget in your web app, offering meaningful Sentry insights for the specific page being viewed through three different **page-aware** panels: Issues, Feedback, and Feature Flags.
+Developers spend a lot of time troubleshooting their web apps on local, staging, and production environments. The Sentry Dev Toolbar pulls data from [sentry.io](http://sentry.io) and surfaces relevant, actionable issues to you when you have the most context for understanding it: as you browse your own site. The Dev Toolbar is a floating widget in your web app, offering meaningful Sentry insights for the specific page being viewed through three different **page-aware** panels: Issues, Feedback, and Feature Flags.
 
 ![Collapsed Dev Toolbar in context of a website](./img/toolbar-collapsed.png)
 
 ## Issues Panel
 
-The issues panel shows you your highest priority frontend [issues](https://docs.sentry.io/product/issues/) for the page you are currently viewing. From the Dev Toolbar, you can quickly jump into specific issues in Sentry to get more detailed information and take action (for example, assign to a team member or mark as resolved). With the issues panel, you can browse the pages that are most important to your business and understand the top issues impacting your user base.
+The issues panel shows you your highest priority frontend [issues](https://docs.sentry.io/product/issues/) for the page you are currently viewing. From the Dev Toolbar, you can quickly jump into specific issues in Sentry to get more detailed information (e.g. Sentry project, issue title, and description, and when the issue was first and last seen) and take action (e.g. assign to a team member or mark as resolved). With the issues panel, you can browse the pages that are most important to your business and understand the top issues impacting your user base.
 
 ![Dev Toolbar with the Issues Panel open](./img/issues-panel.png)
 
 ## Feedback Panel
 
-The feedback panel shows you the most recent user feedback messages for the page you are on, so you can more easily contextualize user feedback. The feedback can include misleading UX, broken links, typos, and so on, covering more bugs and suboptimal experiences than code-thrown errors. The feedback panel works by pulling feedback messages from [Sentry’s User Feedback Widget](https://docs.sentry.io/product/user-feedback/#user-feedback-widget).
+The feedback panel shows you the most recent user feedback messages for the page you are on, so you can more easily contextualize user feedback. The feedback often describes suboptimal experiences that are not strictly code-thrown errors, such as misleading UX, broken links, and typos. The feedback panel works by pulling feedback messages from [Sentry’s User Feedback Widget](https://docs.sentry.io/product/user-feedback/#user-feedback-widget). Just like with the Issues panel, clicking on a particular user feedback will take you to the full detailed User Feedback page within Sentry.
 
 ![Dev Toolbar with the Feedback Panel open](./img/feedback-panel.png)
 
 ## Feature Flags Panel
 
-Feature flags are a powerful tool that allow you to control the visibility of features in your app, enabling you to ship, test, and experiment with confidence. The feature flag panel allows you to quickly view and override feature flags locally that your team has enabled for your web application. You can override any feature flag to be `true` or `false` for your browser session, so you can verify its behavior and observe the impact it might have on errors. Learn more about how to [configure the feature flag panel](/product/dev-toolbar/setup/#implement-feature-flag-adapter).
+Feature flags are a powerful tool that allow you to control the visibility of features in your app, enabling you to ship, test, and experiment with confidence. The feature flag panel allows you to quickly view and override feature flags locally. You can override any feature flag to be `true` or `false` for your browser session, so you can verify its behavior and observe the impact it might have on errors. Learn more about how to [configure the feature flag panel](/product/dev-toolbar/setup/#implement-feature-flag-adapter).
 
-[Learn more](/product/explore/feature-flags/) about what data Sentry can track related to your feature flagging system.
+<Note>
+    [Learn more](/product/explore/feature-flags/) about what data Sentry can track related to your feature flagging system.
+</Note>
 
 ![Dev Toolbar with the Feature Flags Panel open](./img/feature-flags-panel.png)
 
 ## Login Flow
 
-After setting up the Dev Toolbar you’ll see a “Login to Sentry” button floating in the center of the page. Your team will need to click this button and login to Sentry before they can access any information from your Sentry organization.
+After setting up the Dev Toolbar you’ll see a “Login to Sentry” button floating in the center of the page. To access any information from your Sentry organization you have to click this button and login to sentry.
 ![Dev Toolbar login button](./img/login-button.png)
 
-After clicking the button, you should see a pop up for logging in to Sentry.
+After clicking the button, you will see a pop up for logging in to Sentry.
 ![Sentry log in pop up](./img/login-popup.png)
 
 If it's your first time setting up the Dev Toolbar, there will be a button with a link to Sentry's Dev Toolbar settings page to configure your domain.
 ![Dev Toolbar configure domains button](./img/configure-domain.png)
 
-You'll need to add your domain URL to Allowed Origins on Sentry's Dev Toolbar settings page.
+You'll need to add your domain URL to Allowed Origins in Sentry on the Settings > Project > Dev Toolbar page.
 ![Sentry's Dev Toolbar Settings Page](./img/sentry-toolbar-settings.png)
 
-Learn more about [deploying the toolbar to different environments](/product/dev-toolbar/setup/#deploying-to-production--dev-environments), and [conditionally inserting the toolbar script tag](/product/dev-toolbar/setup/#conditionally-inserting-script-tag).
-
-### [Set Up](/product/dev-toolbar/setup)
+Learn more about setting up the toolbar, including configuring a feature flag provider and integrating the toolbar in different environments, on the next page.
diff --git a/docs/product/dev-toolbar/setup.mdx b/docs/product/dev-toolbar/setup.mdx
@@ -16,14 +16,18 @@ description: "Get started with Sentry's Dev Toolbar, bringing critical Sentry in
 </Alert>
 
 You need to complete two steps to get the toolbar rendered on the page:
-1. Add or dynamically inject `<script defer src="https://browser.sentry-cdn.com/sentry-toolbar/latest/toolbar.min.js"></script>` into your web app. This script uses the `defer` attribute so that it does not block document parsing. The script tag can be inserted at the bottom of the page so it doesn’t block other critical Javascript.
+1. Add or dynamically inject the following script into your web app:
+  ```html
+  <script src="https://browser.sentry-cdn.com/sentry-toolbar/latest/toolbar.min.js"></script>
+  ```
+  It is recommended that you add the script tag at the bottom of the page so it doesn’t block other critical JavaScript.
 2. Call `window.SentryToolbar.init(initConfig)` to set up a toolbar instance on each page where you want to see the Dev Toolbar.
     ```html
     <html>
     <head>...</head>
     <body>
         …
-        <script async src="https://browser.sentry-cdn.com/sentry-toolbar/latest/toolbar.min.js"></script>
+        <script src="https://browser.sentry-cdn.com/sentry-toolbar/latest/toolbar.min.js"></script>
         <script>
         window.SentryToolbar.init({ … });
         </script>
@@ -35,7 +39,7 @@ You need to complete two steps to get the toolbar rendered on the page:
 
 If you have called `SentryToolbar.init({...})` to render the toolbar, but now want to manually remove or unmount it from the page, you can call the cleanup function that is returned from `init()`. This will unmount all the injected HTML and CSS. Login credentials will not be removed, so you can re-insert the toolbar and still be authenticated.
 ```html
-<script defer src="https://browser.sentry-cdn.com/sentry-toolbar/latest/toolbar.min.js"></script>
+<script src="https://browser.sentry-cdn.com/sentry-toolbar/latest/toolbar.min.js"></script>
 <script>
   const unmountToolbar = window.SentryToolbar.init({ … });
 
@@ -44,13 +48,39 @@ If you have called `SentryToolbar.init({...})` to render the toolbar, but now wa
 </script>
 ```
 
+## Init Configuration Fields
+
+The following fields can be passed into the `.init()` function.
+
+At minimum, you should be calling `.init()` with these three fields:
+```javascript
+window.SentryToolbar.init({
+  organizationSlug: 'acme',
+  projectIdOrSlug: 'website',
+  environment: 'production'
+});
+```
+
+| Field Name | Type | Description | Default Value |
+| ----- | ----- | ----- | ----- |
+| `organizationSlug` | `string` | The organization that users should login to. For example \'acme\' | *Required Value* |
+| `projectIdOrSlug` | `string \| number` | The project for which this website/webapp is associated. | *Required Value* |
+| `environment (optional)` | `string \| string[] \| undefined` | The environment of this deployment. Used to narrow search results in the Toolbar UI. Set to `undefined` or `""` or `\[\]` if you want to see results from all environments. | `undefined` |
+| `placement (optional)` | `'right-edge' \| 'bottom-right-corner'` | Where to render the toolbar on the screen. | `'right-edge'` |
+| `theme (optional)` | `'system' \| 'dark' \| 'light'` | Whether to use dark or light mode. | `'system'` |
+| `featureFlags (optional)` | `FeatureFlagAdapter \| undefined` | See [Implement FeatureFlagAdapter](/product/dev-toolbar/setup//#implement-feature-flag-adapter) below | `undefined` |
+| `sentryOrigin (optional)` | `string \| undefined` | The origin where Sentry can be found. Used for loading the connection to Sentry, and generating links to the website. For example: `'https://acme.sentry.io'` | `'https://sentry.io'` |
+| `domId (optional)` | `string \| undefined` | The `id` given to the \<div\> that is created to contain the toolbar html. | `'sentry-toolbar'` |
+| `debug (optional)` | `string \| undefined` | A comma separated string of debug targets to enable. Example: `'logging,state'`. If the list contains 'all' or 'true' then all targets will be enabled. Valid targets: `'logging' 'login-success' 'settings' 'state'` | `undefined` |
+| `mountPoint (optional)` | `HTMLElement \| () => HTMLElement \| undefined` | Where to mount the toolbar in the DOM. | `document.body` |
+
 ## Implement Feature Flag Adapter
 
-In order to integrate your Feature Flagging platform with the Dev Toolbar, you will need an Adapter that can read flag data from your provider, and also store and retrieve a list of overrides to apply to your local browser session.
+In order to integrate your Feature Flagging platform with the Dev Toolbar, you will need an adapter that can read flag data from your provider, and also store and retrieve a list of overrides to apply to your local browser session.
 
 We plan to create adapters for OpenFeature and LaunchDarkly soon!
 
-The interface you need to implement for an Adapter is:
+The adapter interface is:
 ```javascript
 type FlagValue = boolean | string | number | undefined;
 type FlagMap = Record<string, FlagValue>;
@@ -80,39 +110,13 @@ interface FeatureFlagAdapter {
    * this specific flag.
    */
     urlTemplate?: undefined | ((name: string) => string | URL | undefined);
-    }
+}
 ```
 
 [MockFeatureFlagIntegration.tsx](https://github.com/getsentry/sentry-toolbar/blob/301c31d561a81e3fd8ffc9532aad3a60af685916/src/env/demo/MockFeatureFlagIntegration.tsx) is an example adapter to use as a reference.
 
-## Init Configuration Fields
-
-The following fields can be passed into the `.init()` function.
-
-For example, a minimal configuration looks like:
-```javascript
-window.SentryToolbar.init({
-  organizationSlug: ‘acme’,
-  projectIdOrSlug: ‘website’,
-  environment: ‘production’
-});
-```
-
-| Field Name | Type | Description | Default Value |
-| ----- | ----- | ----- | ----- |
-| `organizationSlug` | `string` | The organization that users should login to. For example \'acme\' | *Required Value* |
-| `projectIdOrSlug` | `string \| number` | The project for which this website/webapp is associated. | *Required Value* |
-| `environment (optional)` | `string \| string[] \| undefined` | The environment of this deployment. Used to narrow search results in the Toolbar UI. Set to `undefined` or `""` or `\[\]` if you want to see results from all environments. | `undefined` |
-| `placement (optional)` | `'right-edge' \| 'bottom-right-corner'` | Where to render the toolbar on the screen. | `'right-edge'` |
-| `theme (optional)` | `'system' \| 'dark' \| 'light'` | Whether to use dark or light mode. | `'system'` |
-| `featureFlags (optional)` | `FeatureFlagAdapter \| undefined` | See [Implement FeatureFlagAdapter](/product/dev-toolbar/setup//#implement-feature-flag-adapter) above | `undefined` |
-| `sentryOrigin (optional)` | `string \| undefined` | The origin where Sentry can be found. Used for loading the connection to Sentry, and generating links to the website. For example: `'[https://acme.sentry.io]'` | `'https://sentry.io'` |
-| `domId (optional)` | `string \| undefined` | The `id` given to the \<div\> that is created to contain the toolbar html. | `'sentry-toolbar'` |
-| `debug (optional)` | `string \| undefined` | A comma separated string of debug targets to enable. Example: `'logging,state'`. If the list contains 'all' or 'true' then all targets will be enabled. Valid targets: `'logging' 'login-success' 'settings' 'state'` | `undefined` |
-| `mountPoint (optional)` | `HTMLElement \| () => HTMLElement \| undefined` | Where to mount the toolbar in the DOM. | `document.body` |
-
 
-## Deploying To Production & Dev Environments
+## Deploying To Dev, Staging, and Production Environments
 Since the Dev Toolbar is deployed onto specific pages, it's strongly recommended that you consider which environments the toolbar should apply to.
 
 In dev and staging environments, you might want to *unconditionally* include the toolbar so that all developers and testers can use it and quickly go from the page they're looking at back to Sentry for further debugging.
@@ -140,5 +144,5 @@ If the toolbar `<script>` is accidentally included on your site, and `SentryTool
 
 ## Conditionally Inserting Script Tag
 
-It's possible to dynamically insert the script tag inside a single-page app, prior to calling `SentryToolbar.init()`, so that it’s only visible to authorized users. See [`docs/conditional-script.md`](http://conditional-script.md) for example code. This will help reduce network traffic for your users because they do not have the credentials needed to login.
+It's possible to dynamically insert the script tag inside a single-page app, prior to calling `SentryToolbar.init()`, so that it’s only visible to authorized users. See [`docs/conditional-script.md`](https://github.com/getsentry/sentry-toolbar/blob/main/docs/conditional-script.md) for example code. This will help reduce network traffic for your users because they do not have the credentials needed to login.
 This example code will be eventually implemented as an NPM package, but for now it can be done manually.
