Merge pull request #29303 from giantswarm/notification-docs

Slight improvements to the Notifications docs

docs/notifications/index.md

@@ -8,7 +8,7 @@ The Backstage Notifications System provides a way for plugins and external servi
 These notifications are displayed in the dedicated page of the Backstage frontend UI or by frontend plugins per specific scenarios.
 Additionally, notifications can be sent to external channels (like email) via "processors" implemented within plugins.
 
-Notifications can be optionally integrated with the signals (a push mechanism) to ensure users receive them immediately.
+Notifications can be optionally extended with the signals plugin, which provides a push mechanism to ensure users receive notifications immediately.
 
 ### Upgrade to the latest version of Backstage
 
@@ -27,8 +27,8 @@ There are two basic types of notifications:
 Example of use-cases:
 
 - System-wide announcements or alerts
-- Notifications for component owners: e.g., build failures, successful deployments, new vulnerabilities
-- Notifications for individuals: e.g., updates you have subscribed to, new required training courses
+- Notifications for component owners, e.g. build failures, successful deployments, new vulnerabilities
+- Notifications for individuals, e.g. updates you have subscribed to, new required training courses
 - Notifications pertaining to a particular entity in the catalog: A notification might apply to an entity and the owning team.
 
 ## Installation
@@ -87,17 +87,17 @@ import { NotificationsPage } from '@backstage/plugin-notifications';
 
 ### Optional: Add Signals
 
-The use of signals is optional but improves user experience.
+The use of signals is optional but improves the user experience.
 
 #### Optional: Add Signals Backend
 
-Add Signals to your backend by first adding the backend package:
+Add signals to your backend by first adding the backend package:
 
 ```bash title="From your Backstage root directory"
 yarn --cwd packages/backend add @backstage/plugin-signals-backend
 ```
 
-The add the signals to your backend:
+Then add the signals plugin to your backend:
 
 ```ts title="packages/backend/src/index.ts"
 const backend = createBackend();
@@ -156,19 +156,19 @@ add the `UserNotificationSettingsCard` to your frontend.
 
 You can customize the origin names shown in the UI by passing an object where the keys are the origins and the values are the names you want to show in the UI.
 
-Each notification processor will receive its own column in the settings page, where the user can enable or disable notifications from that processor.
+Each notification processor will receive its own row in the settings page, where the user can enable or disable notifications from that processor.
 
 ## Additional info
 
-An example of a backend plugin sending notifications can be found in https://github.com/backstage/backstage/tree/master/plugins/scaffolder-backend-module-notifications.
+An example of a backend plugin sending notifications can be found in the [`@backstage/plugin-scaffolder-backend-module-notifications` package](https://github.com/backstage/backstage/tree/master/plugins/scaffolder-backend-module-notifications).
 
-Sources of the notifications and signal plugins:
+Sources of the notifications and signals plugins:
 
-- https://github.com/backstage/backstage/blob/master/plugins/notifications
-- https://github.com/backstage/backstage/blob/master/plugins/notifications-backend
-- https://github.com/backstage/backstage/blob/master/plugins/notifications-common
-- https://github.com/backstage/backstage/blob/master/plugins/notifications-node
-- https://github.com/backstage/backstage/blob/master/plugins/signals-backend
-- https://github.com/backstage/backstage/blob/master/plugins/signals
-- https://github.com/backstage/backstage/blob/master/plugins/signals-node
-- https://github.com/backstage/backstage/blob/master/plugins/signals-react
+- [notifications](https://github.com/backstage/backstage/blob/master/plugins/notifications)
+- [notifications-backend](https://github.com/backstage/backstage/blob/master/plugins/notifications-backend)
+- [notifications-common](https://github.com/backstage/backstage/blob/master/plugins/notifications-common)
+- [notifications-node](https://github.com/backstage/backstage/blob/master/plugins/notifications-node)
+- [signals-backend](https://github.com/backstage/backstage/blob/master/plugins/signals-backend)
+- [signals](https://github.com/backstage/backstage/blob/master/plugins/signals)
+- [signals-node](https://github.com/backstage/backstage/blob/master/plugins/signals-node)
+- [signals-react](https://github.com/backstage/backstage/blob/master/plugins/signals-react)

docs/notifications/usage.md

@@ -6,7 +6,7 @@ description: How to use the notifications and signals
 
 ## Notifications Backend
 
-The Notifications backend plugin provides an API to create notifications, list notifications per logged-in user, and search based on parameters.
+The notifications backend plugin provides an API to create notifications, list notifications per logged-in user, and search based on parameters.
 
 The plugin uses a relational [database](https://backstage.io/docs/getting-started/config/database) for persistence; no specifics are introduced in this context.
 
@@ -26,7 +26,7 @@ In the `packages/app/src/components/Root/Root.tsx`, tweak the [properties](https
 
 ## Usage
 
-New notifications can be sent either by a backend plugin or an external service through the REST API.
+New notifications can be sent either by a backend plugin or by an external service through the REST API.
 
 ## Backend
 
@@ -71,7 +71,7 @@ await notificationService.send({
 });
 ```
 
-Refer the [API documentation](https://github.com/backstage/backstage/blob/master/plugins/notifications-node/report.api.md) for further details.
+Consult the [API documentation](https://github.com/backstage/backstage/blob/master/plugins/notifications-node/report.api.md) for further details.
 
 ### External Services