Article update updates

Author: chrisda

images/open-a-pull-request-page.png

@@ -14,16 +14,7 @@ If you need to install platyPS on old versions of Windows (Windows 8.1 or Window
 
 If you need to install platyPS on really old versions of Windows (a server running a product that lacks support for WMF 5.1 or its requirements), see the [Install platyPS on really old versions of Windows](#install-platyps-on-older-versions-of-windows) section at the end of this article.
 
-**Notes**:
-
-- You need platyPS v0.14.0 or later (released April 2019). If you have an earlier version of platyPS installed, close all open Windows PowerShell windows where the platyPS module is currently loaded and then run `Update-Module platyPS` from a new elevated Windows PowerShell window. Or, run the command `Remove-Module platyPS` and then run `Install-Module -Name platyPS -Scope CurrentUser` to get the current version.
-
-  For products where all cmdlets aren't baked into the product module itself (Exchange), be aware of the following issues observed in different platyPS versions:
-
-  - v0.14.0: Works fine.
-  - v0.14.1 and v0.14.2: Work fine, but produce bogus/nuisance errors using New-MarkdownHelp that can slow down operation. See this [platyPS GitHub issue](https://github.com/PowerShell/platyPS/issues/509) for details. This issue will likely be fixed in platyPS v2.0.0-Preview3.
-
-  If all cmdlets are baked into the product module itself, you likely won't have these issues, so it doesn't matter which version of platyPS you use.
+You need platyPS v0.14.0 or later (released April 2019). If you have an earlier version of platyPS installed, close all open Windows PowerShell windows where the platyPS module is currently loaded and then run `Update-Module platyPS` from a new elevated Windows PowerShell window. Or, run the command `Remove-Module platyPS` and then run `Install-Module -Name platyPS -Scope CurrentUser` to get the current version.
 
 ## Step 2: Connect to the PowerShell environment that has the cmdlet
 
@@ -35,17 +26,23 @@ You probably know how to do this already, but the available workloads and connec
   > Use `Upgrade-Module` and also `Uninstall-Module` depending on the module version you have installed.
 
 - Exchange:
-  - Exchange Online: [Connect to Exchange Online PowerShell](https://learn.microsoft.com/powershell/exchange/connect-to-exchange-online-powershell)
-  - Security & Compliance: [Connect to Security & Compliance PowerShell](https://learn.microsoft.com/powershell/exchange/connect-to-scc-powershell)
-  - Exchange Online Protection: [Connect to Exchange Online Protection PowerShell](https://learn.microsoft.com/powershell/exchange/connect-to-exchange-online-protection-powershell)
-  - Exchange Server: [Connect to Exchange servers using remote PowerShell](https://learn.microsoft.com/powershell/exchange/connect-to-exchange-servers-using-remote-powershell)
+  - Exchange Online PowerShell: [Connect to Exchange Online PowerShell](https://learn.microsoft.com/powershell/exchange/connect-to-exchange-online-powershell)
+  - Security & Compliance PowerShell: [Connect to Security & Compliance PowerShell](https://learn.microsoft.com/powershell/exchange/connect-to-scc-powershell)
+  - Exchange Online Protection PowerShell: [Connect to Exchange Online Protection PowerShell](https://learn.microsoft.com/powershell/exchange/connect-to-exchange-online-protection-powershell)
+  - Exchange Server PowerShell: [Connect to Exchange servers using remote PowerShell](https://learn.microsoft.com/powershell/exchange/connect-to-exchange-servers-using-remote-powershell)
 
-> [!NOTE]
-> You might need to connect to the service in an elevated Windows PowerShell prompt (Teams and Exchange environments don't require this). The connection instructions article should contain this and other connection requirements.
+> [!TIP]
+> You might need to connect to the service in an elevated Windows PowerShell prompt (Teams and Exchange environments don't require an elevated Windows PowerShell prompt). The connection instructions article should plainly state this and other connection requirements.
+>
+> In Exchange and Security & Compliance PowerShell environments, the cmdlets that are available to you are controlled by role-based access control (RBAC). Most cmdlets and parameters are available to administrators by default, but some aren't (for example, the "Mailbox Search" and "Mailbox Import Export" roles.
 >
-> In Exchange environments, the cmdlets available to you are controlled by role-based access control (RBAC). Most cmdlets and parameters are available to administrators by default, but some aren't (for example, the "Mailbox Search" and "Mailbox Import Export" roles.
+> Remote PowerShell connections are deprecated in Exchange Online PowerShell and Security & Compliance PowerShell in favor of REST API connections. For more information, see the following articles:
 >
-> In v3.0.0 or later of the EXO V3 module, you need to connect to Exchange Online in remote PowerShell mode using the _UseRPSSession_ switch in the **Connect-ExchangeOnline** command. If you omit the _UseRPSSession_ switch and connect in REST API mode, the **Type** value of most parameters will be the incorrect and unhelpful `Object` or `Object[]` values. For more information about the EXO V3 module, see [Updates for version 3.0.0 (the EXO V3 module)](/powershell/exchange/exchange-online-powershell-v2#updates-for-version-300-the-exo-v3-module).
+> - [REST API connections in the EXO V3 module](https://learn.microsoft.com/powershell/exchange/exchange-online-powershell-v2#rest-api-connections-in-the-exo-v3-module).
+> - [Deprecation of Remote PowerShell in Exchange Online](https://techcommunity.microsoft.com/t5/exchange-team-blog/deprecation-of-remote-powershell-in-exchange-online-re-enabling/ba-p/3779692).
+> - [Deprecation of Remote PowerShell (RPS) Protocol in Security & Compliance PowerShell](https://techcommunity.microsoft.com/t5/exchange-team-blog/deprecation-of-remote-powershell-rps-protocol-in-security-and/ba-p/3815432).
+>
+> REST API connections in the Exchange Online PowerShell V3 module incorrectly identify many parameter **Type** values as `Object` or `Object[]`. The true parameter type values are visible in product code.
 
 ## Step 3: Load platyPS in the PowerShell environment
 
@@ -99,83 +96,34 @@ For Microsoft Teams, the module name is always `MicrosoftTeams`.
 
 Either way, take note of your module name. You'll need it in the next steps.
 
-### Step 5: Store your PSSession in a variable
-
-> [!NOTE]
-> This step is required in products that use remote connections to retrieve cmdlets (Exchange). **If you're using a product where all of the cmdlets are baked into the module itself, you can skip this step**.
->
-> As described earlier, you need to connect to Exchange Online in remote PowerShell mode using the _UseRPSSession_ switch in the **Connect-ExchangeOnline** command. Although the [Get-ConnectionInformation](/powershell/module/exchange/get-connectioninformation) cmdlet is a reasonable replacement for Get-PSSession in REST API mode, the output doesn't work with the _Session_ parameter in **New-MarkdownHelp**. For more information about the EXO V3 module, see [Updates for version 3.0.0 (the EXO V3 module)](/powershell/exchange/exchange-online-powershell-v2#updates-for-version-300-the-exo-v3-module).
-
-Do the following steps to store the remote PowerShell connection information to a variable:
-
-1. Run the following command to find your session:
-
-   ```powershell
-   Get-PSSession | Format-Table -Auto
-   ```
-
-   The output will resemble this:
-
-   ```powershell
-   Id Name                           ComputerName          ComputerType  State  ConfigurationName  Availability
-   -- ----                           ------------          ------------  -----  -----------------  ------------
-   1 ExchangeOnlineInternalSession_1 outlook.office365.com RemoteMachine Opened Microsoft.Exchange    Available
-   ```
-
-   > [!NOTE]
-   > If you see multiple sessions, either start over in a new PowerShell window or confirm the session you want to use. The first connection is 1, the second is 2, and so on.
-
-2. Use the following syntax to store the session in a variable:
-
-    ```powershell
-    $<VariableName> = Get-PSSession <SessionID>
-    ```
-  
-    For example, using the sample output in the previous step:
-
-    ```powershell
-    $Session = Get-PSSession 1
-    ```
-
-    The variable name you choose doesn't matter, but you'll use it in later steps.
-
-### Step 6: Run platyPS to generate topic files
+### Step 5: Run platyPS to generate topic files
 
 You have two choices:
 
 - **Dump _all_ cmdlets in the module/snap-in to files**: This is simple but could take a while, and you'll end up with dozens or possibly hundreds of cmdlet files you don't need. The basic syntax is:
 
   ```powershell
-  New-MarkdownHelp -Module <ModuleName> -OutputFolder "<Path"> [-Session <PSSessionVariableName>]
+  New-MarkdownHelp -Module <ModuleName> -OutputFolder "<Path">
   ```
 
 - **Dump specific cmdlets to files**: This is a bit harder to set up, but the output is much quicker, and there are no extra topic files created. The basic syntax is:
 
   ```powershell
-  New-MarkdownHelp -Command <Cmdlet> -OutputFolder "<Path"> [-Session <PSSessionVariableName>]
+  New-MarkdownHelp -Command <Cmdlet> -OutputFolder "<Path">
   ```
 
   or
 
   ```powershell
   $x = "<Cmdlet1>","<Cmdlet2>",..."<CmdletN>"
-  New-MarkdownHelp -Command $x -OutputFolder "<Path"> [-Session <PSSessionVariableName>]
+
+  New-MarkdownHelp -Command $x -OutputFolder "<Path">
   ```
 
 **Notes**:
 
 - \<ModuleName\> is the value you found in [Step 4](#step-4-find-your-module-name) (for example, `tmp_byivwzpq.e1k` or `MicrosoftTeams`).
 
-- \<PSSessionVariableName\> is the session variable from [Step 5](#step-5-store-your-pssession-in-a-variable) (for example, `$Session`) _and is required only if the cmdlets aren't baked into the module_.
-
-  > [!IMPORTANT]
-  > Failure to use the _Session_ parameter in environments that need it leads to weird results in the topic file output. For example:
-  >
-  > - Multiple syntax blocks/parameter sets aren't recognized and are collapsed into one big block.
-  > - The Type value is Object for all parameters.
-  > - The Required value is False for all parameters.
-  > - And more.
-
 - If the \<Path\> ___location doesn't exist, it's created for you.
 
 #### Dump all cmdlets in the module/snap-in to files
@@ -188,25 +136,23 @@ New-MarkdownHelp -Module MicrosoftTeams -OutputFolder "C:\My Docs\Teams"
 
 #### Dump specific cmdlets to files
 
-This example creates a topic file for the cmdlet named **Get-CoolFeature** in the Exchange Online PowerShell session where the session variable is `$Session` in the folder "C:\My Docs\ExO".
+This example creates a topic file for the cmdlet named **Get-CoolFeature** in the Exchange Online PowerShell session in the folder "C:\My Docs\ExO".
 
 ```powershell
-New-MarkdownHelp -Command "Get-CoolFeature" -OutputFolder "C:\My Docs\ExO" -Session $Session
+New-MarkdownHelp -Command "Get-CoolFeature" -OutputFolder "C:\My Docs\ExO"
 ```
 
-This example creates topic files for the **Get-CoolFeature**, **New-CoolFeature**, **Remove-CoolFeature**, and **Set-CoolFeature** cmdlets from the Exchange Online session where the session variable is `$Session` in the folder C:\My Docs\ExO.
+This example creates topic files for the **Get-CoolFeature**, **New-CoolFeature**, **Remove-CoolFeature**, and **Set-CoolFeature** cmdlets from the Exchange Online session in the folder C:\My Docs\ExO.
 
 The first command stores the cmdlet names in a variable. The second command uses that variable to identify the cmdlets and write the output files.
 
 ```powershell
 $NewCmdlets = "Get-CoolFeature","New-CoolFeature","Remove-CoolFeature","Set-CoolFeature"
-```
 
-```powershell
-New-MarkdownHelp -Command $NewCmdlets -OutputFolder "C:\My Docs\ExO" -Session $Session
+New-MarkdownHelp -Command $NewCmdlets -OutputFolder "C:\My Docs\ExO"
 ```
 
-### Step 7: Document the new cmdlet
+### Step 6: Document the new cmdlet
 
 Now that you have topic files for the new cmdlets, you can actually document them. The topics are plain text UTF-8 files that are formatted using [markdown](https://guides.github.com/features/mastering-markdown/). Office writers use [Visual Studio Code](https://code.visualstudio.com/) to edit topic files, but you can use Notepad or your favorite text editor.
 
@@ -242,7 +188,7 @@ schema: 2.0.0
 
 - **external help file**: Defines which MAML/XML file the cmdlet help topic goes in for `Get-Help` at the command line. This value very product-specific, and the ___location is specified somewhere in product code. Some products (Skype) use only one XML file that's well-known and the same for all cmdlets; others (Exchange) use multiple XML files. See other topics for available values. Don't guess; a wrong value here will affect the availability of the help topic at the command line.
 
-- **Module Name**: Not used in Exchange topics (remove it). For other products, this is the module name of the product.
+- **Module Name**: In Exchange topics, this value is `ExchangeOnlineManagement` for those few cmdlets that are [baked into the Exchange Online PowerShell V3 module itself](https://learn.microsoft.com/powershell/exchange/exchange-online-powershell-v2#cmdlets-in-the-exchange-online-powershell-module). For other products, this is the module name of the product.
 
 - **online version**: This is the URL of the topic. This URL value is what makes the `Get-Help <Cmdlet> -Online` command work, so it's very important.
 
@@ -279,16 +225,15 @@ Accept wildcard characters: False
 
 Most of the attributes and values are generated automatically by platyPS. The ones that require manual intervention are:
 
+- **Type**: In any environment, the values `Object` or `Object[]` are wrong. As previously described, REST API connections in the Exchange Online PowerShell V3 module incorrectly identify many parameter **Type** values as `Object` or `Object[]`. Other values like `String`, `Boolean`, and `DateTime` are detected correctly. The true parameter type values are visible in product code.
+
 - **Applicable**: You need to add this attribute and value yourself. Notice the capital 'A'. See other topics for available values (same available values as the **applicable** attribute at the top of the topic). Don't invent new values here. The value **must** come from the list of predefined values.
 
 - **Default value** and **Accept wildcard characters**: These attributes are present, but the values are never truthfully populated by platyPS **or any other PowerShell utility** (they're always None and False, respectively). You can correct the values if you think it's important. Otherwise, leave them as is.
 
-> [!NOTE]
-> If the **Type** value for parameters is `Object`, then something is wrong. In Exchange Online environments, see [Step 2](#step-2-connect-to-the-powershell-environment-that-has-the-cmdlet) for an explanation of remote PowerShell mode vs. REST API mode.
-
 ### Step 8: Add the new cmdlet topic files to the repository
 
-When you're done editing the topics, upload them to GitHub. Note that you need to fork, upload your files to your fork, then submit a Pull Request.
+When you're done editing the topics, upload them to GitHub. Note that you need to fork the repo, upload your files to your fork, and then submit a Pull Request.
 
 1. Go to the correct ___location in the appropriate GitHub repository:
 
@@ -300,40 +245,32 @@ When you're done editing the topics, upload them to GitHub. Note that you need t
    - Whiteboard: <https://github.com/MicrosoftDocs/office-docs-powershell/tree/master/whiteboard/whiteboard-ps/whiteboard>
    - SharePoint / OneDrive: <https://github.com/MicrosoftDocs/OfficeDocs-SharePoint-PowerShell>
 
-2. Click **Upload files**
+2. Select **Add file** \> **Upload files**
 
    ![Upload file.](../images/upload_files.png)
 
-3. After you're done adding files, go to the **Propose file change** section at the bottom of the page:
+3. After you're done adding files, go to the **Propose changes** section at the bottom of the page:
 
    - A brief title is required. By default, the title is the name of the file, but you can change it.
-   - Optionally, you can enter more details in the **Add an optional extended description** box.
+   - Optionally, you can enter more details in the **Add an optional extended description** box. You should @ include the GitHub alias of someone who can review and approve your upload.
 
-   When you're ready, click the green **Propose file change** button.
+   When you're ready, click the green **Propose changes** button.
 
    ![Propose file change section.](../images/propose-file-change.png)
 
-4. On the **Comparing changes** page that appears, click the green **Create pull request** button.
-
-   ![Comparing changes page.](../images/comparing-changes-page.png)
-
-5. On the **Open a pull request** page that appears, click the green **Create pull request** button.
+4. On the **Open a pull request** page that appears, click the green **Create pull request** button.
 
    ![Open a pull request page.](../images/open-a-pull-request-page.png)
 
-> [!NOTE]
->
-> Your permissions in the repo determine what you see. People with no special privileges will see the **Propose file change** section and subsequent confirmation pages as described. People with permissions to create and approve their own pull requests will see a similar **Commit changes** section with extra options for creating a new branch and fewer confirmation pages.
->
-> The point is: click any green buttons that are presented to you until there are no more.
+5. That's it. There's nothing more for you to do.
 
 ### Step 9: Add the new cmdlets to the TOC file
 
 Add the cmdlet to Table of Contents (TOC) file in the GitHub repo. TOC file is the name of the module. For example:
 
 - Exchange <https://github.com/MicrosoftDocs/office-docs-powershell/blob/master/exchange/exchange-ps/exchange/exchange.md>
 
-  > [!NOTE]
+  > [!TIP]
   > Exchange also uses pseudo folders to organize cmdlets. You need to add any new cmdlets in the proper ___location in the file: <https://github.com/MicrosoftDocs/office-docs-powershell/blob/master/exchange/mapping/serviceMapping.json>.
 
 - Office Web Apps: <https://github.com/MicrosoftDocs/office-docs-powershell/blob/master/officewebapps/officewebapps-ps/officewebapps/officewebapps.md>
@@ -348,30 +285,7 @@ Add the cmdlet to Table of Contents (TOC) file in the GitHub repo. TOC file is t
 
 In the TOC file, you can fill in a description or remove the template text line. However, if you leave the template text line make sure it's in _exactly_ the right format so it won't render as a template text.
 
-After you're done editing the TOC files:
-
-1. Go to the **Propose file change** section at the bottom of the page:
-
-   - A brief title is required. By default, the title is the name of the file, but you can change it.
-   - Optionally, you can enter more details in the **Add an optional extended description** box.
-
-   When you're ready, click the green **Propose file change** button.
-
-   ![Propose file change section.](../images/propose-file-change.png)
-
-2. On the **Comparing changes** page that appears, click the green **Create pull request** button.
-
-   ![Comparing changes page.](../images/comparing-changes-page.png)
-
-3. On the **Open a pull request** page that appears, click the green **Create pull request** button.
-
-   ![Open a pull request page.](../images/open-a-pull-request-page.png)
-
-> [!NOTE]
->
-> Your permissions in the repo determine what you see. People with no special privileges will see the **Propose file change** section and subsequent confirmation pages as described. People with permissions to create and approve their own pull requests will see a similar **Commit changes** section with extra options for creating a new branch and fewer confirmation pages.
->
-> The point is: click any green buttons that are presented to you until there are no more.
+The steps to edit and publish the TOC file are identical to modifying any existing topic. The instructions are [here](https://github.com/MicrosoftDocs/office-docs-powershell/blob/main/README.md) (you're starting at Step 4).
 
 ## Appendix