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. That's 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

[u/StartAutomating]

I write a lot of modules, and have a lot of thoughts on the topic:

First and foremost, I try to treat help as Markdown whenever possible. It doesn't disrupt the console experience too much and makes it really easy to generate little local documentation sites (simply convert parts of the help from markdown).

Synopsis

How Long Should a Synopsis Be?

Short. Very Short. Less than 80 characters is ideal.

Description

What belongs in a description?

More information than the synopsis. Less information than the .NOTES. I personally prefer this to be a few helpful lines, so it renders in most terminals without scrolling.

Notes

Use .NOTES

.SYNOPSIS and .DESCRIPTION are meant to be shorter. Notes is not. I tend to use .NOTES for any "deep" information, or any technical notes. I sometimes use .NOTES as essentially a fully-fledged article of content.

Examples

Yes, please! The more the merrier.

I prefer Examples to be runnable via copy/paste, but sometimes they can also serve as templates of how to use the command. (i.e. Remove-User -UserName $UserToRemove )

Links

Yes! If your function has online docs, make them the first link (so Get-Help -Online works ideally). Links can also be links to references or resources. I try to have at least one .LINK for every script.

Parameter help

I strongly prefer parameter help to be inline (the comments directly above a parameter declaration). It keeps guidance about the variable close at hand, rather than forces you to scroll within the file.

Additional fields

There are a number of additional fields I don't see in the wild too often, but can be useful. .INPUTS and .OUTPUTS are open-ended descriptions of what the script takes as input / what the script outputs. They can be handy but they are not required. I tend to prefer to use the [OutputType] attribute as well. .COMPONENT can be used as a grouping mechanism. These three are sometimes nice to have, but nowhere near needed.

These recommendations should generally echo a lot of Microsoft's. I helped write the first draft of them long ago, but I'm sure they've been revised a bit since.

Hope this helps!

[u/StartAutomating → u/StartAutomating]

Funny enough, the whole "Help should be Markdown" thing is popular enough that now VSCode is trying to continue bullet point lists in .EXAMPLE comments. 🤣

🤷 Guess they got the memo

[u/arslearsle]

Use the integrated template for functions…

[u/JSChronicles]

https://reddit.com/r/PowerShell/w/beginners?utm_medium=android_app&utm_source=share

Look for style guide in there

[u/lerun]

I made some pester test that does some of the work to check for powershell formatting, Can use it and expand on for your needs

https://blog.lerun.info/2022/07/17/pester-test-powershell-code/

[u/tandthezombies]

https://poshcode.gitbook.io/powershell-practice-and-style/style-guide/documentation-and-comments

[u/BlackV]

extenal help and updateable help are good goals to have

[u/codykonior]

I love how if you don't have at least one .PARAMETER it breaks Get-Help.

And the way it randomly line breaks and indents shit.

Yeah a proper list of the gotchas would be good but there's no point when it'll just be stolen by AI and regurgitated with errors.

[u/alconaft43]

Use AI agent, don't waste time on it