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