From 52e0b0fcf32fb749c942119a40f5553067b2b9b3 Mon Sep 17 00:00:00 2001
From: Sean Wheeler <sean.wheeler@microsoft.com>
Date: Thu, 24 Mar 2022 14:51:59 -0500
Subject: [PATCH] Replicate changes from docs repo

---
 docs/Rules/ShouldProcess.md | 69 ++++++++++++++++++++-----------------
 1 file changed, 38 insertions(+), 31 deletions(-)

diff --git a/docs/Rules/ShouldProcess.md b/docs/Rules/ShouldProcess.md
index 013fd2e77..5e83e3544 100644
--- a/docs/Rules/ShouldProcess.md
+++ b/docs/Rules/ShouldProcess.md
@@ -1,7 +1,7 @@
 ---
 description: Should Process
 ms.custom: PSSA v1.20.0
-ms.date: 10/18/2021
+ms.date: 03/24/2022
 ms.topic: reference
 title: ShouldProcess
 ---
@@ -16,8 +16,11 @@ If a cmdlet declares the `SupportsShouldProcess` attribute, then it should also
 but makes no calls to `ShouldProcess` or it calls `ShouldProcess` but does not declare
 `SupportsShouldProcess`
 
-For more information, please refer to `about_Functions_Advanced_Methods` and
-`about_Functions_CmdletBindingAttribute`
+For more information, see the following articles:
+
+- [about_Functions_Advanced_Methods](/powershell/modules/microsoft.powershell.core/about/about_Functions_Advanced_Methods)
+- [about_Functions_CmdletBindingAttribute](/powershell/modules/microsoft.powershell.core/about/about_Functions_CmdletBindingAttribute)
+- [Everything you wanted to know about ShouldProcess](/powershell/scripting/learn/deep-dives/everything-about-shouldprocess)
 
 ## How
 
@@ -30,39 +33,43 @@ calling `ShouldProcess`
 ### Wrong
 
 ```powershell
-    function Set-File
-    {
-        [CmdletBinding(SupportsShouldProcess=$true)]
-        Param
-        (
-            # Path to file
-            [Parameter(Mandatory=$true)]
-            $Path
-        )
-        "String" | Out-File -FilePath $FilePath
-    }
+function Set-File
+{
+    [CmdletBinding(SupportsShouldProcess=$true)]
+    Param
+    (
+        # Path to file
+        [Parameter(Mandatory=$true)]
+        $Path
+    )
+    "String" | Out-File -FilePath $Path
+}
 ```
 
 ### Correct
 
 ```powershell
-    function Set-File
-    {
-        [CmdletBinding(SupportsShouldProcess=$true)]
-        Param
-        (
-            # Path to file
-            [Parameter(Mandatory=$true)]
-            $Path
-        )
+function Set-File
+{
+    [CmdletBinding(SupportsShouldProcess=$true)]
+    Param
+    (
+        # Path to file
+        [Parameter(Mandatory=$true)]
+        $Path,
 
-        if ($PSCmdlet.ShouldProcess("Target", "Operation"))
-        {
-            "String" | Out-File -FilePath $FilePath
-        }
-        else
-        {
-            Write-Host ('Write "String" to file {0}' -f $FilePath)
-        }
+        [Parameter(Mandatory=$true)]
+        [string]$Content
+    )
+
+    if ($PSCmdlet.ShouldProcess($Path, ("Setting content to '{0}'" -f $Content)))
+    {
+        $Content | Out-File -FilePath $Path
+    }
+    else
+    {
+        # Code that should be processed if doing a WhatIf operation
+        # Must NOT change anything outside of the function / script
     }
+}
 ```