Change side-by-side instructions and clarify ways to use the Az module while also still using AzureRM.

Author: Stephen Tramer

docs-conceptual/azps-2.0.0/migrate-from-azurerm-to-az.md

@@ -6,7 +6,7 @@ ms.author: sttramer
 manager: carmonm
 ms.devlang: powershell
 ms.topic: conceptual
-ms.date: 12/13/2018
+ms.date: 05/10/2019
 ---
 
 # Migrate from AzureRM to Azure PowerShell Az
@@ -17,7 +17,8 @@ module. To make the transition easier, Az offers tools to allow you to run your
 using AzureRM. No migration to a new command set is ever convenient, but this article will help
 you get started on transitioning to the new module.
 
-To see the full list of breaking changes between AzureRM and Az, see the [Migration guide for Az 1.0.0](migrate-az-1.0.0.md)
+To see the full list of breaking changes between AzureRM and Az, see the
+[Migration guide for Az 1.0.0](migrate-az-1.0.0.md)
 
 ## Check for installed versions of AzureRM
 
@@ -36,28 +37,33 @@ Get-InstalledModule -Name AzureRM -AllVersions
 
 This is the most important step! Run your existing scripts, and make sure that they work with the
 _latest_ release of AzureRM (__6.13.1__). If your scripts don't work, make sure to read
-the [AzureRM migration guide](/powershell/azure/azurerm/migration-guide.6.0.0).
+the [AzureRM 5.x to 6.x migration guide](/powershell/azure/azurerm/migration-guide.6.0.0).
+
+## Uninstall AzureRM
+
+The Az module is not guaranteed to be compatible with any existing AzureRM installs in PowerShell 5.1 for Windows.
+Before you install the Az module, you should [uninstall AzureRM](/powershell/azure/uninstall-az-ps#uninstall-the-azurerm-module).
+
+If you want to keep AzureRM in your local environment, it's possible to do so, but requires that you
+have [PowerShell Core](/powershell/scripting/install/installing-powershell-core-on-windows) 6.x or later
+installed. Then you can keep the AzureRM module installed under PowerShell 5.1 for Windows, and install
+the Az module in PowerShell Core. This unfortunately requires using two different PowerShell environments, but is
+the only way to guarantee success with having both modules installed at once on a system.
 
 ## Install the Azure PowerShell Az module
 
 The first step is to install the Az module on your platform. When you install Az, it's recommended
 that you uninstall AzureRM. In the following steps, you'll learn how to keep running your existing
 scripts and enable compatibility for old cmdlet names.
 
-To install the Azure PowerShell Az module, follow these steps:
+To install the Azure PowerShell Az module, follow the instructions in [Install the Az module](install-az-ps.md).
 
-* __RECOMMENDED__: [Uninstall the AzureRM module](/powershell/azure/uninstall-az-ps#uninstall-the-azurerm-module).
-  Make sure that you remove _all_ installed versions of AzureRM, not just the most recent version.
-* [Install the Az module](install-az-ps.md)
+> [!NOTE]
+> At this point, you might want to run the [Uninstall-AzureRM](/powershell/module/az.accounts/uninstall-azurerm)
+> cmdlet provided in the Az module, just to make sure that all versions of AzureRM have been uninstalled
+> and won't cause conflicts.
 
-## <a name="aliases"/>Enable AzureRM compatibility aliases 
-
-> [!IMPORTANT]
->
-> Only enable compatibility mode if you've uninstalled _all_ versions of AzureRM. Enabling compatibility
-> mode with AzureRM cmdlets still available may result in unpredictable behavior. Skip this step if you
-> decided to keep AzureRM installed, but be aware that any AzureRM cmdlets will use
-> the older modules and not call any Az cmdlets.
+## <a name="aliases"/>Enable AzureRM compatibility aliases
 
 With AzureRM uninstalled and your scripts working with the latest AzureRM version, the next step is to 
 enable the compatibility mode for the Az module. Compatibility is enabled with the command:

docs-conceptual/azps-2.0.0/new-azureps-module-az.md

@@ -1,7 +1,7 @@
 ---
 title: Introducing the Azure PowerShell Az module
 description: Introducing the new Azure PowerShell module Az, the replacement for the AzureRM module.
-ms.date: 12/13/2018
+ms.date: 05/10/2019
 author: sptramer
 ms.author: sttramer
 ms.manager: carmonm
@@ -45,12 +45,25 @@ Azure with PowerShell cmdlets.
 
 ## Upgrade to Az
 
-It's recommended that all users upgrade to the new Az module. To do so:
+To keep up with the latest Azure features in PowerShell, you should migrate to the Az module as soon as
+possible. If you're not ready to install the Az module as a replacement for AzureRM, you have a couple of
+options available to experiment with Az:
 
-* __RECOMMENDED__: [Uninstall the Azure PowerShell AzureRM module](/powershell/azure/uninstall-az-ps#uninstall-the-azurerm-module)
-* [Install the Azure PowerShell Az module](/powershell/azure/install-az-ps)
-* Enable compatibility mode to add aliases for AzureRM cmdlets with `Enable-AzureRMAlias`
-  while you become familiar with the new command set. __Only__ enable aliases if you do not have AzureRM installed.
+* Use a `PowerShell` environment with [Azure Cloud Shell](https://docs.microsoft.com/en-us/azure/cloud-shell/overview).
+  Azure Cloud Shell is an environment which comes with the Az module installed, `Enable-AzureRM` compatibility aliases
+  enabled, and the [Azure CLI](/cli/azure).
+* Keep the AzureRM module installed with PowerShell 5.1 for Windows, but install the Az module for PowerShell Core 6.x
+  or later. PowerShell 5.1 for Windows and PowerShell Core use separate collections of modules. Follow the instructions
+  to [install PowerShell Core](/powershell/scripting/install/installing-powershell-core-on-windows) and then
+  [install the Az module](install-az-ps.md) from a PowerShell Core terminal.
+
+To upgrade from an existing AzureRM install:
+
+1. [Uninstall the Azure PowerShell AzureRM module](/powershell/azure/uninstall-az-ps#uninstall-the-azurerm-module)
+2. [Install the Azure PowerShell Az module](install-az-ps.md)
+3. __OPTIONAL__: Enable compatibility mode to add aliases for AzureRM cmdlets with
+  [Enable-AzureRMAlias](/powershell/module/az.accounts/enable-azurermalias) while you become familiar with
+  the new command set.
 
 ## Migrate existing scripts to Az
 
@@ -69,8 +82,10 @@ in cmdlet names, use `Az`. For example, the old command `New-AzureRMVm` has beco
 
 For a full description of the migration process, see [Migrate from AzureRM to Az](migrate-from-azurerm-to-az.md).
 
-## The future of support for AzureRM
+## Continued support for AzureRM
 
 The existing AzureRM module will no longer receive new cmdlets or features. However, AzureRM is still officially
-maintained and will get bug fixes up through December 2020. To keep up with the latest Azure services and features,
-switch to the Az module.
+maintained and will get bug fixes up through at least December 2020.
+
+The Az module is production-ready, in GA, and does not incur any additional costs on Azure. We recommend
+that you switch to the Az module as soon as possible to keep up with the latest Azure features.

docs-conceptual/azps-2.0.0/uninstall-az-ps.md

@@ -1,7 +1,7 @@
 ---
 title: Uninstall Azure PowerShell
 description: How to perform a complete uninstall of Azure PowerShell
-ms.date: 12/13/2018
+ms.date: 05/10/2019
 author: sptramer
 ms.author: sttramer
 ms.manager: carmonm
@@ -13,7 +13,7 @@ ms.topic: conceptual
 This article tells you how to uninstall an older version of Azure PowerShell, or completely remove it from
 your system. If you've decided to completely uninstall the Azure PowerShell, give us some feedback
 through the [Send-Feedback](/powershell/module/az.accounts/send-feedback) cmdlet.
-If you encounter a bug, we'd appreciate it if you [file a GitHub issue](https://github.com/azure/azure-powershell/issues).
+If you encountered a bug, we'd appreciate it if you [file a GitHub issue](https://github.com/azure/azure-powershell/issues) so that it can be fixed.
 
 ## Uninstall the Az module
 
@@ -40,6 +40,7 @@ The following script queries the PowerShell Gallery to get a list of dependent s
 uninstalls the correct version of each submodule. You will need to have administrator access to run this script
 in a scope other than `Process` or `CurrentUser`.
 
+<a name="uninstall-script"/>
 ```powershell-interactive
 function Uninstall-AllModules {
   param(
@@ -119,7 +120,7 @@ $versions[1..($versions.Length-1)]  | foreach { Uninstall-AllModules -TargetModu
 
 If you have the Az module installed on your system and would like to uninstall AzureRM, there are two options that
 don't require running the `Uninstall-AllModules` script above. Which method you follow depends on how you installed the AzureRM module.
-If you're not sure, follow the steps for uninstalling an MSI first.
+If you're not sure of your original install method, follow the steps for uninstalling an MSI first.
 
 ### Uninstall Azure PowerShell MSI
 
@@ -143,4 +144,9 @@ part of the `Az.Accounts` module. This removes _all_ AzureRM modules from your m
 Uninstall-AzureRm
 ```
 
-If you can't successfully run the `Uninstall-AzureRM` command, use the `Uninstall-AllModules` script provided in this article instead.
+If you can't successfully run the `Uninstall-AzureRM` command, use the [`Uninstall-AllModules` script](#uninstall-script) provided in this article, with the following invocation:
+
+```powershell-interactive
+$versions = (Get-InstalledModule AzureRM -AllVersions | Select-Object Version)
+$versions | foreach { Uninstall-AllModules -TargetModule AzureRM -Version ($_.Version) -Force }
+```