docs: revised Notifications feature page (#25901)

* docs: revised Notifications feature page

* docs: fixed mentions and updated content according to style guide in the notifications feature page

* docs: fixed lint errors in the notifications feature page

* docs: slightly improved consistency of steps in the notifications feature page

* docs: fixed mentions in the notifications feature page

docs/tutorial/notifications.md

@@ -1,17 +1,36 @@
 # Notifications (Windows, Linux, macOS)
 
-All three operating systems provide means for applications to send notifications
+## Overview
-to the user. Electron conveniently allows developers to send notifications with
-the [HTML5 Notification API](https://notifications.spec.whatwg.org/), using
-the currently running operating system's native notification APIs to display it.
 
-**Note:** Since this is an HTML5 API it is only available in the renderer process. If
+All three operating systems provide means for applications to send
-you want to show Notifications in the main process please check out the
+notifications to the user. The technique of showing notifications is different
+for the Main and Renderer processes.
+
+For the Renderer process, Electron conveniently allows developers to send
+notifications with the [HTML5 Notification API](https://notifications.spec.whatwg.org/),
+using the currently running operating system's native notification APIs
+to display it.
+
+To show notifications in the Main process, you need to use the
 [Notification](../api/notification.md) module.
 
-```javascript
+## Example
+
+### Show notifications in the Renderer process
+
+Assuming you have a working Electron application from the
+[Quick Start Guide](quick-start.md), add the following line to the
+`index.html` file before the closing `</body>` tag:
+
+```html
+<script src="renderer.js"></script>
+```
+
+and add the `renderer.js` file:
+
+```js
 const myNotification = new Notification('Title', {
-  body: 'Lorem Ipsum Dolor Sit Amet'
+  body: 'Notification from the Renderer process'
 })
 
 myNotification.onclick = () => {
@@ -19,12 +38,52 @@ myNotification.onclick = () => {
 }
 ```
 
+After launching the Electron application, you should see the notification:
+
+![Notification in the Renderer process](../images/notification-renderer.png)
+
+If you open the Console and then click the notification, you will see the
+message that was generated after triggering the `onclick` event:
+
+![Onclick message for the notification](../images/message-notification-renderer.png)
+
+### Show notifications in the Main process
+
+Starting with a working application from the
+[Quick Start Guide](quick-start.md), update the `main.js` file with the following lines:
+
+```js
+const { Notification } = require('electron')
+
+function showNotification () {
+  const notification = {
+    title: 'Basic Notification',
+    body: 'Notification from the Main process'
+  }
+  new Notification(notification).show()
+}
+
+app.whenReady().then(createWindow).then(showNotification)
+```
+
+After launching the Electron application, you should see the notification:
+
+![Notification in the Main process](../images/notification-main.png)
+
+## Additional information
+
 While code and user experience across operating systems are similar, there
 are subtle differences.
 
-## Windows
+### Windows
-* On Windows 10, a shortcut to your app with an [Application User
+
-Model ID][app-user-model-id] must be installed to the Start Menu. This can be overkill during development, so adding `node_modules\electron\dist\electron.exe` to your Start Menu also does the trick. Navigate to the file in Explorer, right-click and 'Pin to Start Menu'. You will then need to add the line `app.setAppUserModelId(process.execPath)` to your main process to see notifications.
+* On Windows 10, a shortcut to your app with an
+[Application User Model ID][app-user-model-id] must be installed to the
+Start Menu. This can be overkill during development, so adding
+`node_modules\electron\dist\electron.exe` to your Start Menu also does the
+trick. Navigate to the file in Explorer, right-click and 'Pin to Start Menu'.
+You will then need to add the line `app.setAppUserModelId(process.execPath)` to
+your main process to see notifications.
 * On Windows 8.1 and Windows 8, a shortcut to your app with an [Application User
 Model ID][app-user-model-id] must be installed to the Start screen. Note,
 however, that it does not need to be pinned to the Start screen.
@@ -44,7 +103,7 @@ to 200 characters. That said, that limitation has been removed in Windows 10, wi
 the Windows team asking developers to be reasonable. Attempting to send gigantic
 amounts of text to the API (thousands of characters) might result in instability.
 
-### Advanced Notifications
+#### Advanced Notifications
 
 Later versions of Windows allow for advanced notifications, with custom templates,
 images, and other flexible elements. To send those notifications (from either the
@@ -53,40 +112,47 @@ main process or the renderer process), use the userland module
 which uses native Node addons to send `ToastNotification` and `TileNotification` objects.
 
 While notifications including buttons work with `electron-windows-notifications`,
-handling replies requires the use of [`electron-windows-interactive-notifications`](https://github.com/felixrieseberg/electron-windows-interactive-notifications), which
+handling replies requires the use of
-helps with registering the required COM components and calling your Electron app with
+[`electron-windows-interactive-notifications`](https://github.com/felixrieseberg/electron-windows-interactive-notifications),
-the entered user data.
+which helps with registering the required COM components and calling your
+Electron app with the entered user data.
 
-### Quiet Hours / Presentation Mode
+#### Quiet Hours / Presentation Mode
 
-To detect whether or not you're allowed to send a notification, use the userland module
+To detect whether or not you're allowed to send a notification, use the
-[electron-notification-state](https://github.com/felixrieseberg/electron-notification-state).
+userland module [electron-notification-state](https://github.com/felixrieseberg/electron-notification-state).
 
-This allows you to determine ahead of time whether or not Windows will silently throw
+This allows you to determine ahead of time whether or not Windows will
-the notification away.
+silently throw the notification away.
 
-## macOS
+### macOS
 
 Notifications are straight-forward on macOS, but you should be aware of
-[Apple's Human Interface guidelines regarding notifications](https://developer.apple.com/macos/human-interface-guidelines/system-capabilities/notifications/).
+[Apple's Human Interface guidelines regarding notifications][apple-notification-guidelines].
 
 Note that notifications are limited to 256 bytes in size and will be truncated
 if you exceed that limit.
 
-### Advanced Notifications
+[apple-notification-guidelines]: https://developer.apple.com/macos/human-interface-guidelines/system-capabilities/notifications/
+
+#### Advanced Notifications
 
 Later versions of macOS allow for notifications with an input field, allowing the user
 to quickly reply to a notification. In order to send notifications with an input field,
-use the userland module [node-mac-notifier](https://github.com/CharlieHess/node-mac-notifier).
+use the userland module [node-mac-notifier][node-mac-notifier].
 
-### Do not disturb / Session State
+[node-mac-notifier]: https://github.com/CharlieHess/node-mac-notifier
+
+#### Do not disturb / Session State
 
 To detect whether or not you're allowed to send a notification, use the userland module
-[electron-notification-state](https://github.com/felixrieseberg/electron-notification-state).
+[electron-notification-state][electron-notification-state].
 
 This will allow you to detect ahead of time whether or not the notification will be displayed.
 
-## Linux
+[electron-notification-state]: https://github.com/felixrieseberg/electron-notification-state
+
+### Linux
 
 Notifications are sent using `libnotify` which can show notifications on any
 desktop environment that follows [Desktop Notifications