I'm putting together a consistent help template for a team's PowerShell scripts. Is there recognized guidance on how to write sections like .SYNOPSIS, .DESCRIPTION, .PARAMETER, .EXAMPLE, and .NOTES, beyond just what the keywords mean?
Is there a good style guide for PowerShell comment-based help?
Answers
Start with the documentation and comments section of the PowerShell Practice and Style guide. It gives you a community style reference to work from, though you don't have to adopt every recommendation unchanged.
For a comparison, look at the PowerShell documentation source for cmdlet help, such as Get-Process. That can help you see how established documentation separates a short summary, fuller explanation, parameter details, and examples.
Reply to this answer
For a practical template, keep the synopsis very short. A target under 80 characters is one possible team convention, not a requirement. Use the description for what someone needs to understand before running the command, and give parameters and examples enough context to be useful.
Some teams also write help text with Markdown in mind so it can be turned into local documentation. Check how the formatting reads in the console before making that a standard, though.
Reply to this answer
Use a function help template as a starting scaffold, then agree on which sections your team actually requires. A template helps with consistency, but it won't decide whether the explanation or examples are any good.
Reply to this answer
If consistency is the goal, consider Pester checks for the formatting rules you decide on. Automated checks can catch missing or inconsistent structure, while someone reviewing the script checks whether the help actually makes sense.
Reply to this answer
Also consider whether comment-based help is the long-term format you want for everything. External help and updateable help are worth looking into as future goals, especially if the documentation needs to be maintained separately from the code.
Reply to this answer
Add your answer
Answers are reviewed before publication.
q.316+foldmarker:
It's worth treating the style guide as a starting point rather than a Microsoft rulebook. The team's template can explain where it deliberately differs.