Powershell-Copilot-Standards comments.instructions.md

PowerShell Help Content Standards

Generate comprehensive, enterprise-grade help for PowerShell functions that serves as both technical documentation and business communication. Create help that supports automatic README generation and provides full Get-Help functionality.

Where Help Lives

This file defines what good help content contains. Where that content is written depends on whether the function is exported:

Function	Help lives in	Notes
Exported (Public/) in a module	PlatyPS Markdown under docs/ModuleName/	The .ps1 keeps only # .EXTERNALHELP plus a one-line .SYNOPSIS
Private (Private/) in a module	Full comment-based help in the .ps1	PlatyPS never sees these - the comment block is the only documentation
Standalone script or function	Full comment-based help in the .ps1	No module, no MAML, no PlatyPS

Every standard below — description structure, per-parameter content, three progressive examples, enterprise notes — applies in all three cases. Only the file it is typed into changes.

For the generation, update, and build mechanics, see platyps.instructions.md. Do not add detail to a public function's comment block: .EXTERNALHELP makes Get-Help ignore it, so the effort is invisible to users and becomes a second copy that drifts.

Help Generation Requirements

Worked example: Basic-Function-Example.ps1 carries a complete help block in the form described here - synopsis, description, per-parameter text, multiple examples with expected output, and .NOTES with troubleshooting links but no change history. It is a standalone function, so the whole block lives in the .ps1. In a module, that same content is what belongs in the command's Markdown file.

Mandatory Sections

Generate complete comment-based help including all required sections:

.SYNOPSIS

• Use approved PowerShell verbs (Get, Set, New, Remove, etc.)
• Maximum 80 characters
• Focus on primary action and business value
• Avoid technical jargon unless necessary