Provide more guidance for file encoding (#285)

* Provide more guidance for file encoding

* Update HelpFile encoding rule

Author: sdwheeler

reference/docs-conceptual/PSScriptAnalyzer/Rules/UseBOMForUnicodeEncodedFile.md

@@ -1,6 +1,6 @@
 ---
 description: Use BOM encoding for non-ASCII files
-ms.date: 06/28/2023
+ms.date: 01/07/2025
 ms.topic: reference
 title: UseBOMForUnicodeEncodedFile
 ---
@@ -13,6 +13,30 @@ title: UseBOMForUnicodeEncodedFile
 For a file encoded with a format other than ASCII, ensure Byte Order Mark (BOM) is present to ensure
 that any application consuming this file can interpret it correctly.
 
+You can use this rule to test any arbitrary text file, but the intent is to ensure that PowerShell
+scripts are saved with a BOM when using a Unicode encoding.
+
 ## How
 
-Ensure that the file is encoded with BOM present.
+For PowerShell commands that write to files, ensure that you set the encoding parameter to a value
+that produces a BOM. In PowerShell 7 and higher, the following values of the **Encoding** parameter
+produce a BOM:
+
+- `bigendianunicode`
+- `bigendianutf32`
+- `oem`
+- `unicode`
+- `utf32`
+- `utf8BOM`
+
+When you create a script file using a text editor, ensure that the editor is configured to save the
+file with a BOM. Consult the documentation for your text editor for instructions on how to save
+files with a BOM.
+
+## Further reading
+
+For more information, see the following articles:
+
+- [about_Character_Encoding](/powershell/module/microsoft.powershell.core/about/about_character_encoding)
+- [Set-Content](xref:Microsoft.PowerShell.Management.Set-Content)
+- [Understanding file encoding in VS Code and PowerShell](/powershell/scripting/dev-cross-plat/vscode/understanding-file-encoding)

reference/docs-conceptual/PSScriptAnalyzer/Rules/UseUTF8EncodingForHelpFile.md

@@ -1,6 +1,6 @@
 ---
 description: Use UTF8 Encoding For Help File
-ms.date: 06/28/2023
+ms.date: 01/07/2025
 ms.topic: reference
 title: UseUTF8EncodingForHelpFile
 ---
@@ -10,4 +10,24 @@ title: UseUTF8EncodingForHelpFile
 
 ## Description
 
-Check if help file uses UTF-8 encoding.
+Check that an `about_` help file uses UTF-8 encoding. The filename must start with `about_` and end
+with `.help.txt`. The rule uses the **CurrentEncoding** property of the **StreamReader** class to
+determine the encoding of the file.
+
+## How
+
+For PowerShell commands that write to files, ensure that you set the encoding parameter to `utf8`,
+`utf8BOM`, or `utf8NoBOM`.
+
+When you create a help file using a text editor, ensure that the editor is configured to save the
+file in a UTF8 format. Consult the documentation for your text editor for instructions on how to
+save files with a specific encoding.
+
+## Further reading
+
+For more information, see the following articles:
+
+- [System.IO.StreamReader](xref:System.IO.StreamReader.CurrentEncoding%2A)
+- [about_Character_Encoding](/powershell/module/microsoft.powershell.core/about/about_character_encoding)
+- [Set-Content](xref:Microsoft.PowerShell.Management.Set-Content)
+- [Understanding file encoding in VS Code and PowerShell](/powershell/scripting/dev-cross-plat/vscode/understanding-file-encoding)