Apply suggestions from code review

Author: nathan-contino

documentation/asciidoc/services/connect/install.adoc

@@ -16,14 +16,16 @@ Run the following command on your Raspberry Pi to install Connect:
 $ sudo apt install rpi-connect
 ----
 
+You can also install Connect from the Recommended Software application.
+
 After installation, use the `rpi-connect` command line interface to start Connect for your current user:
 
 [source,console]
 ----
 $ rpi-connect on
 ----
 
-Alternatively, if the Connect plugin is running in your menu bar, you can choose "Turn On Raspberry Pi Connect" from the dropdown menu:
+Alternatively, click the Connect icon in the menu bar to open a dropdown menu and select *Turn On Raspberry Pi Connect*:
 
 image::images/turn-on-connect.png[width="80%"]
 

documentation/asciidoc/services/connect/troubleshooting.adoc

@@ -10,21 +10,21 @@
 
 * Browsers intercept certain keys and key combinations. As a result, you can't type these keys into your Connect window. Screen sharing includes a toolbar to simulate some of the most popular intercepted keys.
 
-* When upgrading from version 1 to version 2, ensure to upgrade whichever package you currently have installed before switching between rpi-connect and rpi-connect-lite. This will ensure Connect's services are migrated to the new format, i.e. if you currently have rpi-connect installed:
+* To upgrade from version 1 to version 2, you must first upgrade the package you currently have installed before switching between `rpi-connect` and `rpi-connect-lite`. This ensures that Connect's services properly migrate to the version 2 format. If you currently have `rpi-connect` installed, run the following command:
 +
 [source,console]
 ----
 $ sudo apt install --only-upgrade rpi-connect
 ----
 +
-If you have rpi-connect-lite installed:
+Alternatively, if you currently have `rpi-connect-lite` installed, run the following command:
 +
 [source,console]
 ----
 $ sudo apt install --only-upgrade rpi-connect-lite
 ----
 +
-If successful, you should see the following output during the upgrade:
+You should see output similar to the following during the upgrade, indicating that Connect's services have migrated to the version 2 format:
 +
 [source,console]
 ----
@@ -35,36 +35,37 @@ Replacing globally-enabled rpi-connect services with user-enabled ones...
 
 ==== Screen sharing not available
 
-If Connect states that screen sharing is "unavailable" that means it cannot connect to its dedicated WayVNC service.
+If Connect states that screen sharing is unavailable, it cannot connect to the dedicated Connect WayVNC service.
 
-The first step is to check the status of the WayVNC service:
+To find out more about the cause of the issue, run the following commands to check the status of the Connect WayVNC service:
 
 [source,console]
 ----
 $ systemctl --user status rpi-connect-wayvnc.service
 $ journalctl --user --follow --unit rpi-connect-wayvnc.service
 ----
 
-If it is failing to start or that service isn't found at all, please ensure the following:
+If the service fails to start or doesn't exist, ensure that your environment meets the following criteria:
 
-. You're using rpi-connect version 1.1.0 or later (and not rpi-connect-lite which lacks screen sharing support)
-. You're using a Wayland compositor such as Wayfire (enabled via raspi-config's Advanced Options and on by default for Raspberry Pi 4 and 5 with Raspberry Pi OS Bookworm) and not X11
-. You're using a desktop environment supported by WayVNC, e.g. Raspberry Pi Desktop. (Note that using KDE will switch your Wayland compositor to kwin, which is unsupported.)
-. You have an active graphical desktop session running as the same user as the one you signed into (for most, this means enabling "Desktop Autologin" via raspi-config's System Options)
+. You use `rpi-connect` version 1.1.0 or later.
+. You do not use `rpi-connect-lite`, which lacks screen sharing support.
+. You use a Wayland compositor such as wayfire or labwc, not X. You can control this setting via ``raspi-config``'s Advanced Options.
+. You use a desktop environment supported by WayVNC, e.g. Raspberry Pi Desktop. For instance, using KDE switches your Wayland compositor to kwin, which is unsupported.
+. You have an active graphical desktop session running as the same user as the one you signed into. For most, this means enabling "Desktop Autologin" via ``raspi-config``'s System Options.
 
 ==== Can't connect after restarting or ending SSH session
 
-Connect runs as a user-level service and is therefore only available if there is an active session for the user signed into the service. If you want remote shell access without also having any other login session running, xref:connect.adoc#enable-remote-shell-at-all-times[enable user-lingering] for your user which will keep Connect running at all times.
+Connect runs as a user-level service and is therefore only available if there is an active session for the user signed into the service. If you want remote shell access without also running another login session, xref:connect.adoc#enable-remote-shell-at-all-times[enable user-lingering] for your user, which will keep Connect running at all times.
 
-For screen sharing, Connect can only share an existing graphical desktop session, it does not create entirely new sessions: therefore, there must already be a desktop session in progress. To start such a session automatically on boot, you'll need to enable Desktop Autologin via raspi-config's System Options.
+For screen sharing, Connect can only share an existing graphical desktop session: it does not create entirely new sessions. There must already be a desktop session in progress. To start such a session automatically on boot, enable Desktop Autologin via ``raspi-config``'s System Options.
 
 ==== Networking and firewall issues
 
-Connect is designed to avoid having to make changes to your network and firewall in order to establish a connection but if you have a restrictive network and are having trouble connecting, please check the following:
+Connect avoids changing your network or firewall in order to establish a connection. However, if you have a restrictive network and experience trouble connecting, check the following:
 
-. You can access the Connect API (required for authentication and negotiating the connection between your Raspberry Pi device and your browser), e.g. can you load https://api.connect.raspberrypi.com/up?
-. You can access our STUN server (used to obtain a peer-to-peer connection through local or public networks) on stun.raspberrypi.com and UDP port 3478
-. You can access our TURN servers (used to relay sessions if a peer-to-peer connection through local or public networks can't be made) on turn1.raspberrypi.com, turn2.raspberrypi.com and turn3.raspberrypi.com on TCP ports 3478 or 443, or UDP ports 3478, 443 and 49152-65535
+. Can you access the Connect API, which Connect uses for authentication and connection negotiation between your Raspberry Pi and your browser? To check, load https://api.connect.raspberrypi.com/up?[https://api.connect.raspberrypi.com/up?] on your Raspberry Pi.
+. Can you access the Connect STUN server, which Connect uses to obtain a peer-to-peer connection through local or public networks? To check, ping `stun.raspberrypi.com` on UDP port 3478.
+. Can you access our TURN servers, which Connect uses to relay sessions when a peer-to-peer connection fails? To check, ping `turn1.raspberrypi.com`, `turn2.raspberrypi.com` and `turn3.raspberrypi.com` on TCP ports 3478 or 443, or UDP ports 3478, 443 and 49152 -> 65535.
 
 === View Connect status
 
@@ -73,20 +74,19 @@ To view the current status of the Connect service, run the following command:
 [source,console]
 ----
 $ rpi-connect status
+----
+
+You should see output similar to the following:
+
+----
 Signed in: yes
 Screen sharing: allowed (0 sessions active)
 Remote shell: allowed (0 sessions active)
 ----
 
 The output of this command indicates whether or not you are currently signed in to Connect, as well as the remote services enabled on your Raspberry Pi.
 
-If you see the following, you need to run `rpi-connect on` to start Connect:
-
-[source,console]
-----
-$ rpi-connect status
-✗ Raspberry Pi Connect is not running, run rpi-connect on
-----
+If you see output including "Raspberry Pi Connect is not running, run rpi-connect on", run `rpi-connect on` to start Connect.
 
 === Enable enhanced logging
 
@@ -128,7 +128,7 @@ Override the `rpi-connect-wayvnc` service definition with the following command:
 $ systemctl --user edit rpi-connect-wayvnc
 ----
 
-Enter the following lines of configuration between the comments (note the addition of the `-Ldebug` flag):
+Enter the following lines of configuration between the comments (including the `-Ldebug` flag):
 
 [source,bash]
 ----

documentation/asciidoc/services/connect/use.adoc

@@ -9,11 +9,11 @@ If you're using the Connect plugin for the menu bar, clicking "Turn On Raspberry
 
 image::images/browser-sign-in.png[width="80%"]
 
-Alternatively, you can choose "Sign In…" from the dropdown menu:
+Alternatively, you can choose "Sign In..." from the dropdown menu:
 
 image::images/sign-in.png[width="80%"]
 
-If you don't already have a Raspberry Pi ID, you can xref:id.adoc#create-a-raspberry-pi-id[create one] by clicking "create one for free".
+If you don't already have a Raspberry Pi ID, click *create one for free* to xref:id.adoc#create-a-raspberry-pi-id[create one].
 
 === via the command line
 
@@ -201,7 +201,7 @@ Click on a device name to open the device details page. This screen provides low
 
 image::images/device.png[width="80%"]
 
-Deleting a device from Connect automatically signs you out of Connect on the device. The Connect icon in the menu bar turns grey and the menu only provides a **Sign In…** option.
+Deleting a device from Connect automatically signs you out of Connect on the device. The Connect icon in the menu bar turns grey and the menu only provides a **Sign In...** option.
 
 == Update