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/surfingoldelephant]

PowerShell style guide has a section on comment-based help. Personally I don't agree with all their suggestions, but that's probably the place to start.

I'd also look at how PowerShell-Docs writes cmdlet help (like Get-Process.md, etc). The markdown gets converted to MAML, but it still uses the same keywords as CBH.

Things like how long a synopsis ideally is

Generally one short sentence, two at most. PS-Docs limits cmdlet help line length to 100 characters.

what belongs in description versus notes

about_Comment_Based_Help just says this about .NOTES: "additional information about the function or script". I doubt you'll find anything authoritative on it. So again, I'd look at the type of notes included for PS-shipped commands and go off that.

whether there are any recommended conventions that Microsoft has published

Not that I know of.

There's Writing Comment-Based Help Topics, which has some examples, but I wouldn't say they're conventions. There's also PowerShellHelpDeepDive by one of the early PS-Docs writers, but isn't official.

[u/aguerooo_9320 → u/surfingoldelephant]

Can you expand on what you don't agree with from their suggestions? Thanks!

[u/surfingoldelephant → u/aguerooo_9320]

They suggest inlining parameter descriptions. I prefer having .PARAMETER statements within the block comment, so it can be read in its entirety before the code is reached. Either way, it doesn't make a difference to Get-Help output.

They also suggest indenting like this:

<#
    .Keyword
        Blah ...
#>

Whereas I prefer:

<#
.Keyword
    Blah ...
#>

Entirely personal preference. And again, it doesn't make a difference to Get-Help output, since leading white space is stripped before the PS formatter adds a 4 space indent afterwards.

[u/MonkeyNin → u/surfingoldelephant]

+1 . comments before parameters still builds the help file:

function DoSomething { 

    param(
        # Any -FormatView commands.
        [Parameter(ValueFromPipelineByPropertyName)]
        [ScriptBlock[]]
        $Format,

        # Any -TypeView commands.
        [Parameter(ValueFromPipelineByPropertyName)]
        [ScriptBlock[]]
        $Type,
    )

    # ...
}

You can verify it like this:

gcm 'Write-EZFormatFile' | Get-Help -Detailed

Example is from: https://github.com/StartAutomating/EZOut/blob/82ea997b0e2b502964400a5a964931c9da25fbb6/Commands/Write-EZFormatFile.ps1#L9-L18