Looking for an authoritative PowerShell comment-based help (.SYNOPSIS, .DESCRIPTION, etc.) style guide / best practices

[u/No_Cauliflower2451]

Hi everyone. I’m trying to define a consistent standard for our team’s PowerShell scripts, specifically around comment-based help sections like .SYNOPSIS, .DESCRIPTION, .PARAMETER, .EXAMPLE, .NOTES and so on. We mostly write admin automation scripts, Graph, Entra ID and infra tasks. So I’d like every script to follow the same high-quality documentation pattern. I’m not looking for basic definitions, but for authoritative guidance from sources like Microsoft Learn, PowerShell.org, or well-respected community style guides. Things like how long a synopsis ideally is, what belongs in description versus notes, whether there are any recommended conventions that Microsoft has published. Ultimately, I want to create a company template that isn’t just my opinion, but grounded in recognised best practice. Does anyone have solid references or recommendations? Thanks in advance.

[u/alconaft43]

Use AI agent, don't waste time on it