docs: apply feedback to vulnerability docs

docs/explanations.rst

@@ -34,17 +34,21 @@ selection of some of the commands -- what they do, and how they work.
     explanations/what_refresh_does.md
     explanations/purging_services.md
 
-Vulnerability Commands
+Vulnerability commands
 ======================
 
 Here we'll show you the information related to ``pro vulnerability`` commands.
 
+On any ``pro vulnerability`` command, we consider a vulnerability (CVE or USN) as **fixable**,
+if and only if, at least **one** affected installed package associated with it can
+be fixed. That means that a vulnerability is unfixable if no affected installed packages
+related to the vulnerability can be fixed at the moment.
+
 ..  toctree::
     :maxdepth: 1
 
-    explanations/how_to_interpret_output_of_pro_vulnerability_list.md
-    explanations/how_to_interpret_output_of_pro_vulnerability_show.md
-    explanations/what_is_a_fixable_vulnerability.md
+    explanations/pro_vulnerability_list.md
+    explanations/pro_vulnerability_show.md
 
 Public Cloud Ubuntu Pro
 =======================

docs/explanations/how_to_interpret_output_of_pro_vulnerability_list.rst → docs/explanations/pro_vulnerability_list.rst

@@ -1,11 +1,11 @@
 .. _pro-vulnerability-list:
 
-How to interpret the output of pro vulnerability list
+The pro vulnerability list command
 ********************************************************
 
 In the Pro Client version 35, we introduce the ``pro vulnerability list`` command.
-This commands will display by default all the CVEs that are currently affecting the
-system. Let's take a look on an example when running this command:
+This command displays all the CVEs currently affecting the
+system. Let's take a look at an example when running this command:
 
 .. code-block:: text
 
@@ -29,7 +29,7 @@ system. Let's take a look on an example when running this command:
         8 fixable via Ubuntu Pro (1 critical, 1 high, 4 medium, 1 low, 1 negligible)
         2 fixable via Ubuntu Security (1 high, 1 low)
 
-We can see that the command has three distinct sections. Let's analyze each of them:
+We can see that the command has three distinct sections. Let's analyse each of them:
 
 .. code-block:: text
 
@@ -49,20 +49,20 @@ We can see that the command has three distinct sections. Let's analyze each of t
 The first part of the output is a table showing all **fixable** CVEs in the system.
 The table contains these four distinct columns:
 
-* **VULNERABILITY**: The name of the CVE
-* **PRIORITY**: The ubuntu priority for the CVE
-* **FIX AVAILABLE FROM**: The ubuntu pocket where the fix can be found:
-	* **esm-infra**: Fix is availabe on the esm-infra pocket. This means that user must have esm-infra service enabled through Pro in the machine to access it
-	* **esm-apps**: Fix is availabe on the esm-apps pocket. This means that user must have esm-apps service enabled through Pro in the machine to access it
-	* **fips**:     Fix is availabe on the fips pocket. This means that user must have fips service enabled through Pro in the machine to access it
-	* **fips-updates**: Fix is availabe on the fips-updates pocket. This means that user must have fips-updates service enabled through Pro in the machine to access it
-	* **security**: The ubuntu security pocket
-	* **updates**: The ubuntu updates pocket
-	* **no-fix**: No fix is yet available for this CVE
-* **AFFECTED INSTALLED PACKAGES**: The affected installed packages related to the CVE
+* **VULNERABILITY**: The name of the CVE.
+* **PRIORITY**: The Ubuntu priority for the CVE.
+* **FIX AVAILABLE FROM**: The Ubuntu pocket where the fix can be found:
+	* ``esm-infra``: Fix is availabe from the ``esm-infra`` pocket. The user must have the ``esm-infra`` service enabled through Pro on the machine to access it.
+	* ``esm-apps``: Fix is availabe from the ``esm-apps`` pocket. The user must have the ``esm-apps`` service enabled through Pro on the machine to access it.
+	* ``fips``:     Fix is availabe from the ``fips`` pocket. The user must have the ``fips`` service enabled through Pro on the machine to access it.
+	* ``fips-updates``: Fix is availabe from the ``fips-updates`` pocket. The user must have the ``fips-updates`` service enabled through Pro on the machine to access it.
+	* ``security``: The Ubuntu ``security`` pocket.
+	* ``updates``: The Ubuntu ``updates`` pocket.
+	* ``no-fix``: No fix is available yet for this CVE.
+* **AFFECTED INSTALLED PACKAGES**: The installed packages affected by the CVE.
 
 Finally, note that the table is ordered by **PRIORITY**. This means that CVEs with higher
-priority will appear first on the table.
+priority will appear first in the table.
 
 Now, let's look at the next section:
 
@@ -73,11 +73,11 @@ Now, let's look at the next section:
 
 This section details the CVEs that already have fixes applied for them.
 For example, suppose we have a CVE named **CVE-2021-12345** and this
-CVE affects two packages, pkg1 and pkg2. If the we detect that pkg1 is already fixed
-in the machine even if pkg2 is still affected, we will count this CVE here.
+CVE affects two packages, ``pkg1`` and ``pkg2``. If the we detect that ``pkg1`` is already fixed
+on the machine, then even if ``pkg2`` is still affected, we include this CVE here.
 
 Therefore, this section presents a summary of all CVEs that have at least **one** fix already
-applied for it. Addionally, note that we also display the count by ubuntu priority as well.
+applied for it. Note that we also order the count by Ubuntu priority as well.
 
 Finally, let's look at the last section:
 
@@ -87,13 +87,13 @@ Finally, let's look at the last section:
         8 fixable via Ubuntu Pro (1 critical, 1 high, 4 medium, 1 low, 1 negligible)
         2 fixable via Ubuntu Security (1 high, 1 low)
 
-While the previous section show CVEs with fixes already applied, this section show CVE with fixes
-available, but not yet applied. This means that the user can actively fix those issues by upgrading
-the affected packages. However, note that we also split by the type of service. If the fix is
-available by a service that requires Pro, it will go under **Ubuntu Pro**. If that is not the case,
-we will classify the CVE as **Ubuntu Security** instead. This means that some fixes will only be available
-if the user is attached to a Pro subscription and have the necessary service enabled (i.e. esm-infra).
+While the previous section showed CVEs with fixes already applied, this section shows CVEs with fixes
+available, but not yet applied. The user can actively fix those CVEs by upgrading
+the affected packages. However, note that we also split the vulnerability according to the source of
+the fix. If the fix is
+available from a service that requires Pro, it will fall under **Ubuntu Pro**. Otherwise,
+we will classify the CVE as falling under **Ubuntu Security** instead. This means that some fixes will only be available
+if the user is attached to a Pro subscription and has the necessary service enabled (i.e. ``esm-infra``).
 
-Finally, note that we also group the count by ubuntu priority here as well. If the table is too long,
-breaking the count by priority allows user to better visualize the overal risk of the CVEs without the
-need to look at the whole table to access that information.
+Note that we group the count by Ubuntu priority here as well. If the table is long,
+breaking the count by priority provides better visualisation of the overall risk of the CVEs.

docs/explanations/how_to_interpret_output_of_pro_vulnerability_show.rst → docs/explanations/pro_vulnerability_show.rst

@@ -1,9 +1,11 @@
-How to interpret the output of pro vulnerability show
+.. _pro-vulnerability-show:
+
+The pro vulnerability show command
 *****************************************************
 
-If you suspect that a CVE affects your system and wants to verify
-if that is true, you can use the ``pro vulnerability show`` command for this.
-This command will show you all the related information to a CVE **if** it affects
+If you suspect that a CVE affects your system and want to verify
+that, you can use the ``pro vulnerability show`` command.
+This command shows you all the relevant information about a CVE **if** it affects
 your system.
 
 For example, let's assume that ``CVE-2022-2286`` affects your system and you run:
@@ -39,38 +41,36 @@ You will see an output similar to this one:
    VULNERABILITY  TITLE                AFFECTED INSTALLED PACKAGES
    USN-6270-1     Vim vulnerabilities  vim
 
-Let's break it down the output of this command. We start by telling you some basic information for
+Let's break down the output of this command. It starts with some basic information for
 the CVE:
 
-* **Public URL**: The ubuntu security page for this CVE
+* **Public URL**: The Ubuntu Security page for this CVE
 * **Published at**: The published date for the CVE
-* **Ubunut vulnerability data published at**: The published for the vulnerability data we consume to
-  generate this output
+* **Ubunut vulnerability data published at**: The published date for the vulnerability data we consume to generate this output
 * **APT package information updated at**: The last time the APT state was updated in the system
-  (i.e. running an apt install operation)
-* **Ubuntu priority**: The ubuntu priority for this CVE
+  (i.e. running an ``apt install`` operation)
+* **Ubuntu priority**: The Ubuntu priority for this CVE
 * **CVSS score**: The CVSS score of the CVE
 * **CVESS severity**: The CVSS severity of the CVE
 
 After that, we display the CVE description and related notes (if the CVE has notes).
 
-The next block is now displaying which installed packages in the machine are affected by the CVE.
-Whe are using table to display those affected packages where:
+The next block shows which packages installed on the machine are affected by the CVE.
+We use a table to display the affected packages with the following columns:
 
 * **NAME**: The package name
 * **STATUS**: The CVE status for this package
 * **CURRENT VERSION**: The current installed version of the package
-* **FIXED BY**: The version of that package that fix the CVE issue
-* **FIX AVAILABLE FROM**: The pocket where the fix version can be found on
+* **FIXED BY**: The version of the package that fixes the CVE issue
+* **FIX AVAILABLE FROM**: The pocket where the fix version can be found
 
-Finally, we also display the related USNs to the CVE, in case you want to take a look on them as
-well.
+Finally, we also display any USNs related to the CVE.
 
 What if the CVE doesn't affect my system ?
 ==========================================
 
-If the CVE doesn't affect your system, running the ``pro vulnerability show`` will show
-you the an output like this:
+If the CVE doesn't affect your system, running ``pro vulnerability show`` will show
+you an output like this:
 
 .. code-block:: text
 
@@ -99,13 +99,13 @@ fixed:
     python3.5             vulnerable  3.5.2-2ubuntu0~16.04.13  -         no-fix
     python3.5-minimal     vulnerable  3.5.2-2ubuntu0~16.04.13  -         no-fix
 
-Note that the package status show that it is **vulnerabable** and that the **FIXED BY** and
-**FIX AVAILABLE FROM** column will tell you that no fix is available for the package.
+The status column shows the package is **vulnerabable**, but the **FIXED BY** and
+**FIX AVAILABLE FROM** column tell you that no fix is available for the package.
 
 What if I want to see a USN instead ?
 =====================================
 
-To see information about a USN, you just need to provide a USN name instead. For example,
+To see information about a USN, you can provide a USN name instead. For example,
 to see information about USN-4976-2 you can run:
 
 .. code-block:: bash
@@ -144,8 +144,8 @@ Assuming you are affected by the USN, you might see an output like this:
     CVE-2021-3448  low       dnsmasq
 
 
-Note that the information presented here is similar to the one display for the CVE.
-However, we are not displaying information that is only tied to a CVE, such as
+The information presented here is similar to the output displayed for CVEs.
+However, we do not display information that is only relevant to a CVE, such as
 CVSS score and Ubuntu priority.
 
 Finally, note that the last table is called Related CVEs instead, since we are now

docs/howtoguides.rst

@@ -55,7 +55,7 @@ Vulnerability commands
 .. toctree::
    :maxdepth: 1
 
-   Display USNs that affectt the system... <howtoguides/how_to_display_usns_that_affect_the_system>
+   Display USNs that affect the system... <howtoguides/how_to_display_usns_that_affect_the_system>
    Provide manifest file to commands...  <howtoguides/how_to_use_manifest_file_for_pro_vulnerability>
    Update vulnerability data... <howtoguides/how_to_update_vulnerability_data>
 

docs/howtoguides/how_to_use_manifest_file_for_pro_vulnerability.rst

@@ -1,25 +1,26 @@
 How to provide a manifest file to pro vulnerability commands
 ************************************************************
 
-If you want to provide a manifest file to either ``pro vulnerability show`` or
-``pro vulnerability list``, you can use the flag ``--manifest-file``. For example:
+Let's assume that you want to verify the vulnerability situation of a different
+machine than the one you are using. You can achieve that by providing a **manifest file**
+to either ``pro vulnerability show`` or ``pro vulnerability list`` by providing the flag ``--manifest-file``. For example:
 
 .. code-block:: bash
 
    pro vulnerability list --manifest-file=MANIFEST_FILE_PATH
 
-Now, be aware that when providing a manifest file to either of the commands, we will
-interpret that the manifest file was generated for the **same** ubuntu release the
-the machine is running on. For example, if you are running on the command on Xenial
-machine and provides a manifest for the command, the command will believe that the
-manifest also represents a Xenial machine. If that is not the case, you **need** to
-provide the ``--series`` parameter to the command as well, to provide the command
-with the ubuntu release the manifest was generated on, for example:
+When providing a manifest file to either of the commands, it is assumed
+that the manifest file was generated for the **same** Ubuntu series the
+the machine is running on. For example, if you run the command on a Xenial
+machine, and provide a manifest file for the command, the command will assume that the
+manifest also represents a Xenial machine. If that is not the case, you must
+provide the ``--series`` parameter to the command as well, to provide the Ubuntu series the
+manifest was generated on, for example:
 
 .. code-block:: bash
 
    pro vulnerability list --manifest-file=MANIFEST_FILE_PATH --series=focal
 
-Finally, today we only support the manifest file generated by the Pro client. This
+Currently, we only support manifest files generated by the Pro Client. This
 manifest file can be generated by using the
 :ref:`package_manifest<references/api:u.security.package_manifest.v1>` API endpoint.