Docs: Minor updates, rewording for UI extensions (#1997)

Co-authored-by: Levente Balogh <[email protected]>

Author: urbiz-grafana

docusaurus/docs/how-to-guides/ui-extensions/create-an-extension-point.md

@@ -17,7 +17,7 @@ keywords:
 
 import ExtensionPoints from '@shared/extension-points.md';
 
-An _extension point_ is a part of your plugin UI or Grafana UI where other plugins can add links or React components via hooks. You can use them to extend the user experience based on a context exposed by the extension point.
+An _extension point_ is a part of your plugin or Grafana UI where other plugins can add links or React components via hooks. You can use them to extend the user experience based on a context exposed by the extension point.
 
 Read more about extensions under [key concepts](../../key-concepts/ui-extensions.md).
 

docusaurus/docs/how-to-guides/ui-extensions/expose-a-component.md

@@ -11,7 +11,9 @@ keywords:
 sidebar_position: 30
 ---
 
-Expose components to allow app plugins to easily share functionality with other app plugins. Compared to [registering an extension](./register-an-extension), they do not require the extension provider to explicitly register a component against any extension points, and can therefore be [used by any app plugin](./use-an-exposed-component.md) with no action required by the provider.
+Expose components to allow app plugins to easily share functionality with other app plugins without extension points. 
+
+Compared to [registering an extension](./register-an-extension), when you expose a component you do not require the other extension providers to explicitly register their extensions against any extension points. Therefore the component may be [used by any app plugin](./use-an-exposed-component.md) with no action required by the provider.
 
 ## Best practices
 

docusaurus/docs/how-to-guides/ui-extensions/register-an-extension.md

@@ -13,23 +13,23 @@ sidebar_position: 20
 
 import ExtensionPoints from '@shared/extension-points.md';
 
-An _extension_ is a plugin-defined link or a React component that is rendered in either the core Grafana UI or in another app plugin.
+Extensions are links or React components in an app plugin. Extensions are linked to an extension point and they either render in the core Grafana UI or in another app plugin. They can also work as functions returning values. 
 
-Compared to [exposing a component](./expose-a-component.md), they are explicitly registered against one or more extension point IDs. This can be more appropriate when looking to extend Grafana's core UI, or for when you need more control over what should be allowed to use your plugin's extension.
+You can either register or expose an extension. Compared to [just exposing a component](./expose-a-component.md), when you register an extension against one or more extension point IDs you can control who has access to your components. This can be more appropriate when looking to extend Grafana's core UI, or for when you need more control over what should be allowed to use your plugin's extension.
 
 Read more about extensions under [key concepts](../../key-concepts/ui-extensions.md).
 
 <ExtensionPoints/>
 
 :::warning
 
-You must [update](#updating-pluginjson-metadata) your `plugin.json` metadata to list any registered extensions.
+You must [update](#update-the-pluginjson-metadata) your `plugin.json` metadata to list any registered extensions.
 
 :::
 
-## Links
+## Work with link extensions
 
-### Register a link
+### Register a link extension
 
 You can add an extension for a link. For example:
 
@@ -138,15 +138,17 @@ export const plugin = new AppPlugin().addLink({
 });
 ```
 
-## Components
+## Work with component extensions
 
 ### Best practices for adding components
 
 - **Use the props** - check what props the extension point is passing to the components and use them to implement a more tailored experience.
 - **Wrap your component with providers** - if you want to access any plugin specific state in your component make sure to wrap it with the necessary React context providers (e.g. for Redux).
 - **Use the enum for Grafana extension point IDs** - if you are registering a component to one of the available Grafana extension points, make sure that you use the [`PluginExtensionPoints` enum exposed by the `@grafana/data`](https://github.com/grafana/grafana/blob/main/packages/grafana-data/src/types/pluginExtensions.ts#L121) package.
 
-### Register a component
+### Register a component extension
+
+You can register a component extension. For example:
 
 ```tsx
 import { PluginExtensionPoints } from '@grafana/data';
@@ -159,7 +161,7 @@ export const plugin = new AppPlugin().addComponent({
 });
 ```
 
-### Accessing plugin meta in a component
+### Access the plugin's meta in a component
 
 You can use the `usePluginContext()` hook to access any plugin specific meta information inside your component. The hook returns a [`PluginMeta`](https://github.com/grafana/grafana/blob/main/packages/grafana-data/src/types/plugin.ts#L62) object. This can be useful because the component that you register from your plugin won't be rendered under the React tree of your plugin, but somewhere else in the UI.
 
@@ -180,7 +182,9 @@ export const plugin = new AppPlugin().addComponent({
 });
 ```
 
-### Access plugin state in a component
+### Access the plugin's state in a component
+
+To access the plugin's state, do the following:
 
 ```tsx
 import { PluginExtensionPoints } from '@grafana/data';
@@ -223,9 +227,9 @@ export const plugin = new AppPlugin().addComponent({
 });
 ```
 
-## Updating plugin.json metadata
+## Update the plugin.json metadata
 
-Once you have defined a link or component extension to be registered against an extension point, you must update your `plugin.json` metadata.
+After you have defined a link or component extension and registered it against an extension point, you must update your `plugin.json` metadata.
 
 For example:
 
@@ -244,18 +248,14 @@ For more information, see the `plugin.json` [reference](../../reference/metadata
 
 ## Troubleshooting
 
-### My link is not appearing
+If you cannot see your link or component extension check the following: 
+
+1. **Check the console logs** - your link or component may not be appearing due to validation errors. Look for the relevant logs in your browser's console.
+1. **Check the `targets`** - make sure that you are using the correct extension point IDs, and always use the `PluginExtensionPoints` enum for Grafana extension points.
+1. **Check the links `configure()` function** - if your link has a `configure()` function which is returning `undefined`, the link is hidden.
+1. **Check your component's implementation** - if your component returns `null` it won't be rendered at the extension point.
+1. **Check if you register too many links or components** - certain extension points limit the number of links or components allowed per plugin. If your plugin registers more links or components for the same extension point than the allowed amount, some of them may be filtered out.
+1. **Check the Grafana version** - link and component extensions are only supported after Grafana version **`>=10.1.0`**. `addLink()` and `addComponent()` are only supported in versions **>=`11.1.0`**. 
 
-1. **Check the console logs** - there is a good chance that your link is not appearing due to some validation errors. In this case you should see some relevant logs in your browser's console.
-1. **Check the `targets`** - make sure that you are using the correct extension point ids (always use the `PluginExtensionPoints` enum for Grafana extension points)
-1. **Check the links `configure()` function** - in case your link has a `configure()` function it can happen that it is returning `undefined` under certain conditions, which hides the link.
-1. **Check if you register too many links** - certain extension points limit the number of links allowed per plugin, and in case your plugin registers more than one links for the same extension point there is a chance that some of them are filtered out.
-1. **Check the Grafana version** - link and component extensions are only supported after Grafana version **`>=10.1.0`**, while `addLink()` is only supported in versions **>=`11.1.0`**.
 
-### My component is not appearing
 
-1. **Check the console logs** - there is a good chance that your component is not appearing due to some validation errors. In this case you should see some relevant logs in your browser's console.
-1. **Check the `targets`** - make sure that you are using the correct extension point ids (always use the `PluginExtensionPoints` enum for Grafana extension points)
-1. **Check your components implementation** - in case your component returns `null` under certain conditions, then it won't be rendered at the extension point.
-1. **Check if you register too many components** - certain extension points limit the number of components allowed per plugin, and in case your plugin registers more than one component for the same extension point there is a chance that some of them are filtered out.
-1. **Check the Grafana version** - link and component extensions are only supported after Grafana version **`>=10.1.0`**, while `addComponent()` is only supported in versions **>=`11.1.0`**.

docusaurus/docs/key-concepts/ui-extensions.md

@@ -12,34 +12,41 @@ keywords:
 sidebar_position: 60
 ---
 
-Use UI extensions to contribute new actions and functionality to the core Grafana UI and other app plugins.
+Use UI extensions to contribute new actions and functionality to the core Grafana UI and other app plugins. 
 
-## Definition of terms
+## Understand extensions
 
-Before we go into details we need to cover the two major concepts in the UI extensions framework:
+The UI extensions framework is built around these concepts:
 
-1. `Extension point` - A place in the UI where plugins can contribute new functionality to the end user. The Grafana UI exposes extension points and app plugins can also define their own extension points.
-2. `Extension` - New functionality, registered by an app plugin, appearing at an extension point. For example, an extension could provide a navigational link to bring users to a particular view, it could open a modal menu allowing the user to configure an action to take from within their current context (for instance, to create a SLO), or it could trigger background tasks.
+1. `Extension point` - A place in the UI where plugins can contribute new functionality to the end user. Both the Grafana UI and app plugins can expose extension points. 
+2. `Extension` - New functionality you register to an extension point. For example, an extension can provide a navigational link to bring users to a particular view, open a modal menu allowing the user to configure an action to take from within their current context (for instance, to create a SLO), or trigger background tasks. There are three types of extensions: links, components, and functions.
+3. `Exposed component` - A component from an app plugin you can expose to easily share functionality with other app plugins without having to register to an extension point.  
+
+After you have added an extension point to your UI you can extend it multiple times by multiple plugins.
+
+## Where can I find extensions?
 
 ![Panel menu showing available extensions](/img/ui-extensions-menu.png)
 
-In the example above, there is one extension point with three registered extensions. This highlights one of the benefits of using UI extensions. Once you have added an extension point to your UI you can extend it multiple times by multiple plugins.
+In the example above, there is one extension point with three registered extensions: Machine learning, Outlier detection, and Create forecast. 
 
 ## Why should I add an extension point?
 
 App plugins can provide custom pages in the Grafana UI, often highly contextualized to a particular service or task to enable users to be productive. Grafana is a feature-rich observability platform and has an extensive ecosystem of plugins, allowing users to monitor and act upon a wide set of data.
 
 Extension points facilitate the breaking down of silos between individual views, allowing users to quickly leverage data from their current context to take relevant actions. By providing extension points within your app, relevant extensions can easily offer new capabilities to your shared users.
 
-Add an extension point to your UI to give benefits such as these:
+Adding an extension point to your UI provides the following benefits:
 
 - Define the UI extension point once to enable multiple plugins to extend your UI with new functionality. You don't need any additional effort to provide functionality from more plugins in your UI.
 - Clean separation of concerns. Your application doesn't need to know anything about the plugin extending your UI.
 - Integration built for change. Since your application doesn't know anything about the internal workings of the plugin extending your UI, they are free to change their APIs without the risk of breaking the extension point UI.
 - Easy to bootstrap. If both apps are installed and enabled, then the extensions are automatically configured and displayed to the user. There is no need for either app to include custom logic to detect the presence of the other.
 - Extensions are fast. We pre-build the extensions registry at Grafana boot time which makes it fast to use while rendering the UI.
 
-Examples where it would be useful:
+### Use cases
+
+You can use extensions for the following scenarios:
 
 - The user views a dashboard with historical data. By adding an extension point to this part of the UI, a machine learning app plugin can give the user the ability to create a forecast for that data directly from the panel.
 - The user views a firing alert. By adding an extension point to this part of the UI, an Incident app plugin can give the user the ability to create an incident directly from the alert view.
@@ -51,4 +58,4 @@ Examples where it would be useful:
 - [Learn how to expose components from a plugin so other plugins can import them](../how-to-guides/ui-extensions/expose-a-component.md)
 - [Learn how to use exposed components](../how-to-guides/ui-extensions/use-an-exposed-component.md)
 - [Learn how to version exposed components and extension points](../how-to-guides/ui-extensions/versioning-extensions.md)
-- [Check the API reference](../reference/ui-extensions.md)
+- [Check the API reference guide](../reference/ui-extensions.md)

docusaurus/docs/reference/ui-extensions.md

@@ -73,8 +73,8 @@ The method returns the `AppPlugin` instance to allow for chaining.
 
 #### Examples
 
-- [Accessing plugin meta-data in the component](../how-to-guides/ui-extensions/register-an-extension.md#accessing-plugin-meta-in-a-component)
-- [Access your plugin's state inside the component](../how-to-guides/ui-extensions/register-an-extension.md#access-plugin-state-in-a-component)
+- [Accessing plugin meta-data in the component](../how-to-guides/ui-extensions/register-an-extension.md#access-the-plugins-meta-in-a-component)
+- [Access your plugin's state inside the component](../how-to-guides/ui-extensions/register-an-extension.md#access-the-plugins-state-in-a-component)
 - [Hide a component in certain conditions](../how-to-guides/ui-extensions/register-an-extension.md#hide-a-component-in-certain-conditions)
 
 #### See also