Polishing updates

CONTRIBUTING.md

@@ -7,10 +7,10 @@ from the architecture of the project to how you should test any code changes.
 
 ### How to Guides
 
-* [How to build](https://github.com/canonical/ubuntu-pro-client/blob/docs/dev-docs/howtoguides/building.md)
-* [How to run the code formatting tools](https://github.com/canonical/ubuntu-pro-client/blob/docs/dev-docs/howtoguides/code_formatting.md)
-* [How to run the tests](https://github.com/canonical/ubuntu-pro-client/blob/docs/dev-docs/howtoguides/testing.md)
-* [How to release a new version](https://github.com/canonical/ubuntu-pro-client/blob/docs/dev-docs/howtoguides/how_to_release_a_new_version_of_ua.md)
+* [How to build](/dev-docs/howtoguides/building.md)
+* [How to run the code formatting tools](/dev-docs/howtoguides/code_formatting.md)
+* [How to run the tests](/dev-docs/howtoguides/testing.md)
+* [How to release a new version](/dev-docs/howtoguides/release_a_new_version.md)
 * [How to use the contract staging environment](https://github.com/canonical/ubuntu-pro-client/blob/docs/dev-docs/howtoguides/use_staging_environment.md)
 * [How to use the magic attach endpoints](https://github.com/canonical/ubuntu-pro-client/blob/docs/dev-docs/howtoguides/how_to_use_magic_attach_endpoints.md)
 * [How to spellcheck messages](https://github.com/canonical/ubuntu-pro-client/blob/docs/dev-docs/howtoguides/spellcheck.md)

dev-docs/documentation/contribute_docs.md

@@ -18,15 +18,15 @@ in the same repository as the codebase, there are two separate branches for the
 docs:
 
 - The `docs` branch, where the latest documentation is kept. This branch is
-  used to track releases and is published in `Read The Docs`;
+  used to track releases and is published in
+  [Read The Docs](https://canonical-ubuntu-pro-client.readthedocs-hosted.com/en/latest);
 - The `docs-devel` branch, where the documentation of upcoming features and
   changes is kept until they are ready to be released.
 
-When a pull request with improvements or new content to the documentation
-contains features which are not released yet, it should target the
-`docs-devel` branch. Fixes, improvements, and content for existing features can
-target the `docs` branch directly, so they are published immediately after the
-pull request is merged.
+When a pull request with documentation improvements or new content is related to
+not-yet-released features, it should target the `docs-devel` branch. Fixes,
+improvements, and content for existing features can target the `docs` branch
+directly, so they are published immediately after the pull request is merged.
 
 ## Building the docs locally
 
@@ -57,18 +57,23 @@ command:
 $ make run
 ```
 
-This will build *and serve* the documentation at http://127.0.0.1:8000 -- this
-gives you a live preview of any changes you make (and save) to the
+This will build *and serve* the documentation at `http://127.0.0.1:8000` --
+this gives you a live preview of any changes you make (and save) to the
 documentation without needing to continually rebuild.
 
 ## Doc testing
 
-Before running the `make` command, make sure to download the Python venv module by running the following command:
+Before running the `make` command, make sure to download the Python `venv`
+module by running the following command:
+
 ```sh
 apt install python3-venv
 ```
-When working with any `docs` branch and making updates, you can run the documentation tests using the Makefile. 
-The `make` command lists all targets to test. You can run individual targets using the command:
+
+When working with any `docs` branch and making updates, you can run the
+documentation tests using the Makefile. The `make` command lists all targets to
+test. You can run individual targets using the command:
+
 ```bash
 make target
 ```

dev-docs/documentation/styleguide.md

@@ -1,21 +1,14 @@
 # Documentation style guide
 
-Our documentation is *primarily* written in standard Markdown, but pages can
-be written in reStructuredText if you prefer. Our docs are hosted on
-[Read the Docs](https://readthedocs.com/). 
-
-We also use the
-[MyST-Parser Sphinx extension](https://myst-parser.readthedocs.io/en/latest/intro.html).
-This causes all Markdown (.md) files to be parsed as MyST, and
-[enables the use of directives](https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html),
-which can be awkward to achieve in standard Markdown.
+Our documentation is written in
+[reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html)
+and hosted on [Read the Docs](https://readthedocs.com/).
 
 ## General tips and style guide
 
 Documentation consistency (in terms of writing style) is vital for a good user
 experience. We use the [Canonical style guide](https://docs.ubuntu.com/styleguide/en)
-in our documentation, which is summarised below -- with a few additions
-relevant to our docs.
+in our documentation, which is summarised below -- with a few additions.
 
 To make it more straightforward to publish your contribution, we recommend that
 you:
@@ -26,27 +19,21 @@ you:
   expected.
 * Link back to other (reputable) pages on a topic, rather than repeating their
   content.
-* Expand your acronyms the first time they appear on the page, e.g.
-  JavaScript Object Notation (JSON).
 * Try not to assume that your reader will have the same knowledge as you. If
   you’re covering a new topic (or something complicated) then try to briefly
   explain, or link to, things the average reader may not know.
 * If you have used some references you think would be generally helpful to your
   reader, feel free to include a “Further reading” section at the end of the
   page.
-* Unless a list item includes punctuation, don’t end it with a full stop. If
-  one item in the list needs a full stop, add one to all the items.
-
-  If your list items are longer than a sentence or two each, consider whether
-  it might be better to use sub-headings instead, so that they appear in the
-  in-page navigation menu (on the right-hand side of the screen).
+* If your list items are longer than a sentence or two each, consider using
+  sub-headings instead, so that they appear in the in-page navigation menu (on
+  the right-hand side of the screen).
 
 ### Language
 
-Where possible, text should be written in UK English. However, discretion and
-common sense can both be applied. For example, where text refers to code
-elements that exist in US English, the spelling of these elements should not
-be changed to UK English.
+Where possible, text should be written in UK English. However, common sense can
+be applied. For example, where text refers to code elements in US English, the
+spelling of these elements should follow the code (and stay in US English).
 
 ### Voice
 
@@ -57,29 +44,29 @@ could say "we recommend" (active) rather than "it is recommended that"
 
 ### Headings
 
-Headings should be written in sentence case. This means that only the first
+Headings must be written in sentence case. This means that only the first
 letter is capitalised (unless the header text refers to e.g., a product name
 that would normally be capitalised, such as "Ubuntu Pro Client").
 
-Try not to skip heading levels in your document structure, i.e., a level 2
-header (##) should always be followed by a level 3 sub-header (###) not level
-4.Skipping header levels can lead to de-ranking of pages in search engines.
+Avoid skipping heading levels in your document structure, i.e., a level 2
+header should always be followed by a level 3 sub-header and not level 4.
 
 Try to craft your headings to be descriptive, but as short as possible, to help
 readers understand what content to expect on the page.
 
 ### Line length
 
-Please keep the line lengths to a maximum of **79** characters. This ensures
-that the pages and tables do not get so wide that side scrolling is required.
+Please keep the line lengths to a maximum of **79** characters where possible.
+This ensures that the pages and tables do not get so wide that side scrolling
+is required.
 
 ### Links
 
-Where possible, use contextual text in your links to aid users with screen
-readers and other accessibility tools. For example, "check out our
-[documentation style guide](#links) is preferable to "click
-[here](#links) for more" because it provides a larger link area and also helps
-readers to understand what the link contains.
+Use contextual text in your links to aid users with screen readers and other
+accessibility tools. For example, use something like "check out our
+[documentation style guide](#links) rather than "click [here](#links) for more"
+because it provides a larger link area and also helps readers to understand
+what the link contains.
 
 ### Code blocks
 
@@ -88,15 +75,18 @@ Our documentation uses the
 which creates a small button on the right-hand side of code blocks for users to
 copy the code snippets we provide.
 
-You can create a code block by using three backticks ``` and including the
-language (for syntax highlighting):
+You can create a code block by using the ``.. code-block::`` directive and
+including the language (for syntax highlighting). E.g:
 
 ```
-  ```yaml
-  Some code block here
-  ```
+.. code-block:: yaml
+
+   Some code block here
 ```
 
+There must be an empty line before AND after the `code-block` directive, and
+the code block contents must be indented at least three spaces to be recognised.
+
 Using "text" as the language is useful for displaying command output or plain
 text, since it does not highlight anything.
 
@@ -107,71 +97,89 @@ block to the commands. The output should be preceded with a small description
 that explains what’s happening. For example:
 
 ```
-  ```bash
-  uname -r
-  ```
+.. code-block:: bash
+
+   uname -r
+
+Produces the following output:
 
-  Produces the following output:
+.. code-block:: text
 
-  ```text
-  4.14.151
-  ```
+   4.14.151
 ```
 
-Use a single backtick to mark inline commands and other string literals, like
+Use a double backtick to mark inline commands and other string literals, like
 paths to files. This will render them in monospaced font within the paragraph.
 
-### Vertical whitespace
+### Vertical empty space
 
-One newline between each section helps ensure readability of the documentation
-source code. Keeping paragraphs relatively short (up to ~5-6 sentences) aids in
-keeping the text readable when rendered to a web page. Some rST elements also
-require an empty newline before and after, so for consistency, ensure that all
-elements (tables, images, headers, etc) have a newline before and after.
+One new line between each section ensures readability of the documentation
+source code. Short paragraphs (up to ~5--6 sentences) aids in keeping text
+readable when rendered to a web page.
+
+Some rST elements require an empty line before and after, so for consistency,
+ensure that all elements (tables, images, headers, etc) have a new line before
+and after.
 
 ### Acronyms and jargon
 
 Acronyms are always capitalised (e.g., JSON, YAML, QEMU, LXD) in text.
 
-The first time an acronym is used on a page, it is best practice to introduce
-it by showing the expanded name followed by the acronym in parentheses. E.g.,
-Quick EMUlator (QEMU). If the acronym is *very* common (e.g., URL, HTTP), or
-you provide a link to a documentation page with these details, you do not need
-to include them.
+The first time an acronym is used on a page, introduce it by showing the
+expanded name followed by the acronym in parentheses. E.g., Quick EMUlator
+(QEMU). If the acronym is *very* common (e.g., URL, HTTP), or you provide a
+link to a documentation page with these details, you do not need to include
+them.
 
 Avoid using jargon unless absolutely necessary, to keep our documentation
 accessible to as wide a range of users as possible. If jargon is unavoidable,
-consider including brief explanations to help the user keep up with the
-material.
+include brief explanations to help the user understand the material.
 
 ### Admonitions and callouts
 
 Notes, warnings, or other information you wish to draw the reader's attention
-to can be called out in an admonition block. If you are writing your code in
-Markdown, this is where the MyST extension comes in handy. Here is an example:
-
-````
-  ```{note}
-  The options are: note, important, hint, seealso, tip, attention, caution,
-  warning, danger, and error.
-  ```{warning}
-  Although it's possible to nest admonitions inside each other, it's better to
-  avoid doing that unless it's strictly necessary!
-  ```
-````
-
-```{note}
-The options are: note, important, hint, seealso, tip, attention, caution,
-warning, danger, and error.
-```{warning}
-Although it's possible to nest admonitions inside each other, it's better to
-avoid doing that unless it's strictly necessary!
+to can be called out in an admonition block. Here is an example:
+
+```
+.. note::
+
+   The options are: ``note``, ``important``, ``hint``, ``seealso``, ``tip``,
+   ``attention``, ``caution``, ``warning``, ``danger``, and ``error``.
+      
+   .. warning::
+      Although it's possible to nest admonitions like this, it's better to
+      avoid doing that unless it's strictly necessary!
 ```
 
+In general, it's best to use as few admonitions as possible. Having too many
+of these boxes on the page can lead to users ignoring them. 
+
+
+### Add a diagram
+
+Our documentation builds are configured to allow the use of
+[mermaid](https://mermaid.js.org/) for diagrams.
+
+Mermaid blocks can be included in a reStructuredText file with the following
+syntax:
+
+```
+.. mermaid::
+   <code block here>
+```
+
+If you have trouble getting the Mermaid diagram to render, check to make sure
+you have included empty lines before and after the ``.. mermaid::`` line, and
+that your Mermaid code is indented as it would be for a code block. 
+
+These links may be helpful to get started if you're new to Mermaid:
+
+- `The mermaid live online editor <https://mermaid.live/edit>`_
+- `Mermaid syntax for creating a flowchart <https://mermaid.js.org/syntax/flowchart.html?id=flowcharts-basic-syntax>`_
+
 ### Getting advice
 
 If you are in any doubt, please contact our team's
 [Technical Author (Sally)](https://github.com/s-makin) for guidance. If you
 would like her to review any documentation, she would be very happy to help!
-Please also tag her as a reviewer on any PR that contains documentation
-elements.
+Tag her as a reviewer on any PR that contains documentation.

dev-docs/explanations/autoattach_mechanisms.md

@@ -1,19 +1,28 @@
 # Mechanisms for auto-attaching Ubuntu Pro Cloud instances
 
 > **Note**
-> This document explains the systemd units that attempt to auto-attach in various scenarios. If you're interested in how auto-attach itself works, see [How auto-attach works](./how_auto_attach_works.md).
+> This document explains the systemd units that attempt to auto-attach in
+> various scenarios. If you're interested in how auto-attach itself works, see
+> [How auto-attach works](how_auto_attach_works.md).
 
-There are three methods by which a cloud instance may auto-attach to become Ubuntu Pro.
+There are three methods by which a cloud instance may auto-attach to become an
+Ubuntu Pro cloud instance.
 
 1. On boot auto-attach for known Pro cloud instances.
-2. Upgrade-in-place for non-Pro instances that get modified via the Cloud platform to entitle them to become Ubuntu Pro (only on Azure and GCP for now).
+2. Upgrade-in-place for non-Pro instances modified via the Cloud platform to
+   entitle them to become Ubuntu Pro (only on Azure and GCP for now).
 3. Retry auto-attach in case of failures.
 
-(1) is handled by a systemd unit (`ua-auto-attach.service`) delivered by a separate package called `ubuntu-advantage-pro`. This package is only installed on Ubuntu Pro Cloud images. In this way, an instance launched from an Ubuntu Pro Cloud image knows that it needs to auto-attach.
+(1) is handled by a systemd unit (`ua-auto-attach.service`) delivered by a
+separate package called `ubuntu-pro-auto-attach`. This package is only
+installed on Ubuntu Pro Cloud images. In this way, an instance launched from an
+Ubuntu Pro Cloud image knows that it needs to auto-attach.
 
-(2) and (3) are both handled in a systemd unit (`ubuntu-advantage.service`) that is present on all Ubuntu machines (including non-Pro).
+(2) and (3) are both handled in a systemd unit (`ubuntu-advantage.service`)
+that is present on all Ubuntu machines (including non-Pro).
 
-Below is a flow chart intended to describe how all of these methods and systemd units interact.
+Below is a flow chart intended to describe how all of these methods and systemd
+units interact.
 
 ```mermaid
 graph TD;

dev-docs/explanations/early_review_signoff.md

@@ -1,12 +1,14 @@
 # Early review sign-off
-As the Client has a very broad exception for SRUs, there are some features which
+
+As the Pro Client has a broad exception for SRUs, there are some features which
 need pre-evaluation from people outside the team.
 
 This pre-evaluation should be performed at specification time, even before any
 implementation, to prevent frustration from any side when trying to SRU and to
 avoid possible blockers for the process.
 
 The review for such special features must be performed by:
+
 1. A SRU team member, and
 2. Someone from the Ubuntu Core Development team with appropriate expertise on
    the topic being changed.
@@ -29,8 +31,8 @@ jobs
 - Actions that take place without an explicit user opt-in*
 
 New items may be eventually added to this list
-(preferrably before any problem happens!).
+(preferably before any problem happens!).
 
 
-\* executing a CLI command to perform a specific task counts a
-   opt-in for that task.
+\* Executing a CLI command to perform a specific task counts as an opt-in for
+that task.