docs: Improve style consistency everywhere, improve flow in setup pre…

…requisites (#695) Touched up titles in Navigation to remove "How to" or to include just the abbreviation. Restyled "Ubuntu Pro for WSL" everywhere *except for first occurrence on the website, in the home, and the install page) as just "UP4W". Touched up See, See first, See more, See also style in all the docs - See: used when we link to something else for the entire content of a point - See also: used at the top of a HTG section to link to the immediately relevant reference - See more: used in HTGs to link to reference bits used in the HTG or in Reference to link to external pages for more info - See first: used in the UP4W Dev docs to link to the bits that the dev doc is adding to. In the setup HTG, turned Prerequisites into a Check that you meet requirements section. Also touched up the content to improve flow.
canonical · Mar 19, 2024 · ecdc45f · ecdc45f
2 parents b04e20b + 523abb4
commit ecdc45f
Show file tree

Hide file tree

Showing 18 changed files with 244 additions and 103 deletions.
diff --git a/docs/dev/howto/02-install.md b/docs/dev/howto/02-install.md
@@ -1,18 +1,18 @@
-# How to install Ubuntu Pro for WSL
+# How to install UP4W
 
-This guide will show you how to install Ubuntu Pro for WSL for local development and testing.
+This guide will show you how to install UP4W for local development and testing.
 
-## Install Ubuntu Pro for WSL from scratch
+<br/>
 
-### Requirements
+**Requirements:**
 
 - A Windows machine with access to the internet
 - Appx from the Microsoft Store:
   - Windows Subsystem For Linux
   - Either Ubuntu, Ubuntu 22.04, or Ubuntu (Preview)
 - The Windows Subsystem for Windows optional feature enabled
 
-### Download
+## 1. Download the Windows Agent and the  WSL Pro Service
 <!-- TODO: Update when we change were artifacts are hosted -->
 1. Go to the [repository actions page](https://github.com/canonical/ubuntu-pro-for-wsl/actions/workflows/qa-azure.yaml?query=branch%3Amain+).
 2. Click the latest successful workflow run.
@@ -24,7 +24,7 @@ This guide will show you how to install Ubuntu Pro for WSL for local development
 Notice that, for the step above, there is also an alternative version of the MSIX bundle enabled for end-to-end testing. Most likely, that's not what you want to download.
 
 (dev::install::agent)=
-### Install the Windows agent
+## 2. Install the Windows Agent
 
 This is the Windows-side agent that manages the distros.
 
@@ -41,7 +41,7 @@ This is the Windows-side agent that manages the distros.
 6. The Firewall may ask for an exception. Allow it.
 7. The GUI should show up. You’re done.
 
-### Install the WSL Pro Service
+## 3. Install the WSL Pro Service
 
 This is the Linux-side component that talks to the agent. Choose one or more distros Jammy or greater, and follow the instructions.
 

diff --git a/docs/dev/howto/03-restart.md b/docs/dev/howto/03-restart.md
@@ -1,12 +1,12 @@
-# How to restart Ubuntu Pro for WSL
+# How to restart UP4W
 
-Some configuration changes only apply when you restart Ubuntu Pro for WSL. Here is a guide on how to restart it.
+Some configuration changes only apply when you restart UP4W. Here is a guide on how to restart it. There are two options.
 
-## Option 1: Restart your machine
+## Option 1: Restart your UP4W host machine
 
 This is the simple one. If you're not in a hurry to see the configuration updated, just wait until next time you boot your machine.
 
-## Option 2: Restart only Ubuntu Pro for WSL
+## Option 2: Restart only UP4W
 
 1. Stop the agent:
 

diff --git a/docs/dev/howto/06-access-the-logs.md b/docs/dev/howto/06-access-the-logs.md
@@ -1,8 +1,8 @@
-# How to access the logs
+# How to access UP4W logs
 
-At some point you may want to read the logs of Ubuntu Pro for WSL, most likely for debugging purposes. The agent and the service store their logs separately. This guide shows you where to find each of the logs.
+At some point you may want to read the UP4W logs, most likely for debugging purposes. The agent and the service store their logs separately. This guide shows you where to find each of the logs.
 
-## WSL Pro service
+## Access the logs for the WSL Pro service
 
 To access the logs of a specific distribution's WSL-Pro-Service, you must first launch the distribution and then query the journal:
 
@@ -14,9 +14,9 @@ For more information on using the journal, you can check out its man page with `
 
 These logs may be insufficient for proper debugging, so you may be interested in looking at the agent's logs as well.
 
-## Windows agent
+## Access the logs for the Windows Agent
 
-Follow these steps to access the logs for the Windows agent.
+To access the logs for the Windows Agent:
 
 1. Go to your home directory
    - Open the file explorer

diff --git a/docs/dev/howto/index.md b/docs/dev/howto/index.md
@@ -7,8 +7,8 @@ These how-to guides cover key operations and processes in Ubuntu Pro for WSL.
 ```{toctree}
 :titlesonly:
 
-02-install
-03-restart
-06-access-the-logs
-reset-factory
+Install UP4W <02-install>
+Restart UP4W <03-restart>
+Access UP4W logs <06-access-the-logs>
+Reset UP4W <reset-factory>
 ```
diff --git a/docs/dev/reference/07-windows-agent-command-line-reference.md b/docs/dev/reference/07-windows-agent-command-line-reference.md
@@ -1,6 +1,7 @@
-# Windows Agent command-line reference
+# Windows Agent CLI
+
+> See first: [UP4W - Windows Agent](ref::up4w-windows-agent)
 
-The Windows Agent is the component that runs on the host Windows machine.
 
 ## Usage
 

diff --git a/docs/dev/reference/08-wsl-pro-service-command-line-reference.md b/docs/dev/reference/08-wsl-pro-service-command-line-reference.md
@@ -1,6 +1,6 @@
-# WSL-Pro-Service command-line reference
+# WSL Pro Service CLI
 
-The WSL Pro Service is the component that runs on each guest Ubuntu distro.
+> See first: [UP4W - WSL Pro Service](ref::up4w-wsl-pro-service)
 
 ## Usage
 

diff --git a/docs/dev/reference/index.md b/docs/dev/reference/index.md
@@ -8,7 +8,7 @@ The reference material in this section provides technical descriptions of Ubuntu
 :titlesonly:
 
 
-Windows Agent command line interface <07-windows-agent-command-line-reference>
-WSL Pro Service command line interface <08-wsl-pro-service-command-line-reference>
-QA process reference <09-qa-process-reference>
+Windows Agent CLI <07-windows-agent-command-line-reference>
+WSL Pro Service CLI <08-wsl-pro-service-command-line-reference>
+QA process <09-qa-process-reference>
 ```
diff --git a/docs/howto/index.md b/docs/howto/index.md
@@ -2,10 +2,10 @@
 
 # How-to guides
 
-These how-to guides cover key operations and processes in Ubuntu Pro for WSL.
+These how-to guides cover key operations and processes in UP4W.
 
 ```{toctree}
 :titlesonly:
 
-set-up-up4w
+Install and configure UP4W <set-up-up4w>
 ```