Merge pull request #1983 from TerryGLee/tglee-vsinstall

update Installation Options screenshot and add caveat to new command-line option

Author: Ja-Dunn

docs/install/media/installation-options-by-location.png

@@ -49,7 +49,7 @@ When there is an update, there's a corresponding notification flag in Visual Stu
      Your update continues. Then, when it's complete, Visual Studio restarts.
 
      > [!NOTE]
-     > If you run Visual Studio in administrator mode, you must manually restart Visual Studio after the update.    
+     > When you run Visual Studio in administrator mode, you must manually restart Visual Studio after the update.
 
 ### Use the IDE
 
@@ -66,7 +66,7 @@ You can check for an update and then install the update from the menu bar in Vis
    The update proceeds as described in the previous section, and then Visual Studio restarts after the update completes successfully.
 
    > [!NOTE]
-   > If you run Visual Studio in administrator mode, you must manually restart Visual Studio after the update.  
+   > When you run Visual Studio in administrator mode, you must manually restart Visual Studio after the update.
 
 ### Use the Visual Studio Installer
 

docs/install/update-visual-studio.md

@@ -55,7 +55,7 @@ The command-line options are used in conjunction with the setup bootstrapper, wh
 | `--installPath <dir>` | The installation directory for the instance to act upon. For the install command, this is **Optional** and is where the instance will be installed. For other commands, this is **Required** and is where the previously installed instance was installed. |
 | `--addProductLang <language-locale>` | **Optional**: During an install or modify operation, this determines the UI language packs that are installed to the product. It can appear multiple times on the command line to add multiple language packs. If not present, the installation uses the machine locale. For more information, see the [List of language locales](#list-of-language-locales) section on this page.|
 | `--removeProductLang <language-locale>` | **Optional**: During an install or modify operation, this determines the UI language packs that are to be removed from the product. It can appear multiple times on the command line to add multiple language packs. For more information, see the [List of language locales](#list-of-language-locales) section on this page.|
-| `--add <one or more workload or component IDs>` | **Optional**: One or more workload or component IDs to add. The required components of the artifact are installed, but not the recommended or optional components. You can control additional components globally using `--includeRecommended` and/or `--includeOptional`. For finer-grained control, you can append `;includeRecommended` or `;includeOptional` to the ID (for example, `--add Workload1;includeRecommended` or `--add Workload2;includeRecommended;includeOptional`). For more information, see our [Workload and component IDs](workload-and-component-ids.md) page. You can repeat this option as necessary.|
+| `--add <one or more workload or component IDs>` | **Optional**: One or more workload or component IDs to add. The required components of the artifact are installed, but not the recommended or optional components. You can control additional components globally using `--includeRecommended` and/or `--includeOptional`. For finer-grained control, you can append `;includeRecommended` or `;includeOptional` to the ID (for example, `--add Workload1;includeRecommended` or `--add Workload2;includeRecommended;includeOptional`). For more information, see the [Workload and component IDs](workload-and-component-ids.md) page. You can repeat this option as necessary.|
 | `--remove <one or more workload or component IDs>` | **Optional**: One or more workload or component IDs to remove. For more information, see our [Workload and component IDs](workload-and-component-ids.md) page. You can repeat this option as necessary.|
 | `--in <path>` | **Optional**: The URI or path to a response file.  |
 | `--all` | **Optional**: Whether to install all workloads and components for a product. |
@@ -64,7 +64,7 @@ The command-line options are used in conjunction with the setup bootstrapper, wh
 | `--includeOptional` | **Optional**: Includes the optional components for any workloads that are installed, but not the recommended components. The workloads are specified either with `--allWorkloads` or `--add`.  |
 | `--quiet, -q` | **Optional**: Do not display any user interface while performing the installation. |
 | `--passive, -p` | **Optional**: Display the user interface, but do not request any interaction from the user. |
-| `--norestart` | **Optional**: If present, commands with `--passive` or `--quiet` will not automatically restart the machine (if required).  This is ignored if neither `--passive` nor `--quiet` are specified.  |
+| `--norestart` | **Optional**: If present, commands with `--passive` or `--quiet` will not automatically restart the machine (if necessary).  This is ignored if neither `--passive` nor `--quiet` are specified.  |
 | `--nickname <name>` | **Optional**: This defines the nickname to assign to an installed product. The nickname cannot be longer than 10 characters.  |
 | `--productKey` | **Optional**: This defines the product key to use for an installed product. It is composed of 25 alphanumeric characters either in the format `xxxxx-xxxxx-xxxxx-xxxxx-xxxxx` or `xxxxxxxxxxxxxxxxxxxxxxxxx`. |
 | `--help, --?, -h, -?` | Display an offline version of this page. |
@@ -75,12 +75,12 @@ The command-line options are used in conjunction with the setup bootstrapper, wh
 | ----------------------- | --------------- |
 | `--layout <dir>` | Specifies a directory to create an offline install cache. For more information, see [Create a network-based installation of Visual Studio](create-a-network-installation-of-visual-studio.md).|
 | `--lang <one or more language-locales>` | **Optional**: Used with `--layout` to prepare an offline install cache with resource packages with the specified language(s). For more information, see the [List of language locales](#list-of-language-locales) section on this page.|
-| `--add <one or more workload or component IDs>` | **Optional**: One or more workload or component IDs to add. The required components of the artifact are installed, but not the recommended or optional components. You can control additional components globally using `--includeRecommended` and/or `--includeOptional`. For finer-grained control, you can append `;includeRecommended` or `;includeOptional` to the ID (for example, `--add Workload1;includeRecommended` or `--add Workload2;includeOptional`). For more information, see our [Workload and component IDs](workload-and-component-ids.md) page. <br/>**Note**: If `--add` is used, only the specified workloads and components and their dependencies are downloaded. If `--add` is not specified, all workloads and components are downloaded to the layout.|
+| `--add <one or more workload or component IDs>` | **Optional**: One or more workload or component IDs to add. The required components of the artifact are installed, but not the recommended or optional components. You can control additional components globally using `--includeRecommended` and/or `--includeOptional`. For finer-grained control, you can append `;includeRecommended` or `;includeOptional` to the ID (for example, `--add Workload1;includeRecommended` or `--add Workload2;includeOptional`). For more information, see the [Workload and component IDs](workload-and-component-ids.md) page. <br/>**Note**: If `--add` is used, only the specified workloads and components and their dependencies are downloaded. If `--add` is not specified, all workloads and components are downloaded to the layout.|
 | `--includeRecommended` | **Optional**: Includes the recommended components for any workloads that are installed, but not the optional components. The workloads are specified either with `--allWorkloads` or `--add`. |
 | `--includeOptional` | **Optional**: Includes the recommended *and* optional components for any workloads being included in the layout. The workloads are specified with `--add`.  |
 | `--keepLayoutVersion` | **New in 15.3, optional**: Apply changes to the layout without updating the version of the layout. |
-| `--verify` | **New in 15.3, optional**: Verify the contents of a layout.  Any corrupt or missing files are listed. |
-| `--fix` | **New in 15.3, optional**: Verify the contents of a layout.  If any files are found to be corrupt or missing, they are re-downloaded.  Internet access is required to fix a layout. |
+| `--verify` | **New in 15.3, optional**: Verify the contents of a layout. Any corrupt or missing files are listed. |
+| `--fix` | **New in 15.3, optional**: Verify the contents of a layout.  If any files are found to be corrupt or missing, they are redownloaded. Internet access is required to fix a layout. |
 | `--clean <one or more paths to catalogs>` | **New in 15.3, optional**: Removes old versions of components from a layout that has been updated to a newer version. |
 
 | **Advanced install options** | **Description** |
@@ -97,8 +97,8 @@ The command-line options are used in conjunction with the setup bootstrapper, wh
 | `--noUpdateInstaller` | **New in 15.2, optional**: If present, prevents the installer from updating itself when quiet is specified. The installer will fail the command and return a non-zero exit code if noUpdateInstaller is specified with quiet when an installer update is required. |
 | `--noWeb` | **New in 15.3, optional**: Setup now downloads any content that it is installing from the Internet.  All content that is being installed must be available in an offline layout.  If the layout is missing content, setup fails.  For more information, see [Deploying from a network installation](create-a-network-installation-of-visual-studio.md). |
 | `--path <name>=<path>` | **New in 15.7, optional**: Used to specify custom install paths for the installation. Supported path names are shared, cache, and install. |
-| `--path cache=<path>` | **New in 15.7, optional**: Uses the location you specify to download installation files. This location can only be set the first time Visual Studio is installed. Example: `--path cache="C:\VS\cache"` |
-| `--path shared=<path>` | **New in 15.7, optional**: Contains shared files for side-by-side Visual Studio installations. Some tools and SDKs install to a location on this drive, while some others might override this setting and install to another drive. Example: `--path shared="C:\VS\shared"` |
+| `--path cache=<path>` | **New in 15.7, optional**: Uses the location you specify to download installation files. This location can only be set the first time that Visual Studio is installed. Example: `--path cache="C:\VS\cache"` |
+| `--path shared=<path>` | **New in 15.7, optional**: Contains shared files for side-by-side Visual Studio installations. Some tools and SDKs install to a location on this drive, while some others might override this setting and install to another drive. Example: `--path shared="C:\VS\shared"` <br><br>Important: This can be set only once and on the first time that Visual Studio is installed. |
 | `--path install=<path>` | **New in 15.7, optional**: Equivalent to `–-installPath`. Specifically, `--installPath "C:\VS"` and `--path install="C:\VS"` are equivalent. Only one of these can be used at a time. |
 
 ## List of workload IDs and component IDs
@@ -109,24 +109,24 @@ For a list of workload and component IDs sorted by Visual Studio product, see th
 
 | **Language-locale** | **Language** |
 | ----------------------- | --------------- |
-| cs-CZ | Czech |
-| de-DE | German |
-| en-US | English |
-| es-ES | Spanish |
-| fr-FR | French |
-| it-IT | Italian |
-| ja-JP | Japanese |
-| ko-KR | Korean |
-| pl-PL | Polish |
-| pt-BR | Portuguese - Brazil |
-| ru-RU | Russian |
-| tr-TR | Turkish |
-| zh-CN | Chinese - Simplified |
-| zh-TW | Chinese - Traditional |
+| Cs-cz | Czech |
+| De-de | German |
+| En-us | English |
+| Es-es | Spanish |
+| Fr-fr | French |
+| It-it | Italian |
+| Ja-jp | Japanese |
+| Ko-kr | Korean |
+| Pl-pl | Polish |
+| Pt-br | Portuguese - Brazil |
+| Ru-ru | Russian |
+| Tr-tr | Turkish |
+| Zh-cn | Chinese - Simplified |
+| Zh-tw | Chinese - Traditional |
 
 ## Error codes
 
-Depending on the result of the operation, the `%ERRORLEVEL%` environment variable will be set to one of the following values:
+Depending on the result of the operation, the `%ERRORLEVEL%` environment variable is set to one of the following values:
 
 | **Value** | **Result** |
 | --------- | ---------- |