[feature-request] Mandatory parameters on top of list in md files generated by New-MarkdownHelp

[iricigor]

In Powershell documentation, Microsoft is grouping parameters in two groups: Required and Optional. See example for command New-Module here. This helps a lot to quickly identify parameters that matter the most.

Can something like this be implemented in New-MarkdownHelp command?

The command is already parsing all parameters, so I think it will be easy to implement. If grouping would be a problem, then at least sorting?

In standard PowerShell, you can identify mandatory parameters with

((gcm New-Module).ParameterSets.Parameters | ? IsMandatory).Name | Select -Unique

[vors]

Yes, sorting makes sense. Should be easy to add a switch to New-MarkdownHelp and Update-MarkdownHelp. Adding a header ## Required Parameters would alternate the schema and this is a pretty big change with backward compatibility problems and such, so I'd prefer not going this route.

[BernieWhite]

If you look at the source the .md files, they don't distinguish optional and required parameters it is done in a separate process, likely docfx. Docfx does the .md to html conversation and other post processing.

https://github.com/PowerShell/PowerShell-Docs/blob/staging/reference/6/Microsoft.PowerShell.Core/New-Module.md

[sdwheeler]

@iricigor @vors We (Microsoft) are getting rid of the grouping of parameters (mandatory vs. optional). The distinction is not valid. What is mandatory in one parameter set may be optional or non-existent in another parameter set.

The syntax blocks are the only way to accurately and concisely document what is mandatory or optional.

[iricigor]

Hi @sdwheeler, thanks for the feedback.

I would say that "mandatory in at least one parameter set" is valid distinction, but yes, it is somehow hard for understanding. The same problem with "mandatory parameter and multiple parameter sets" goes all the way back into very Get-Help command, which has the same issue.

Do you have any other ideas how to help admins to distinguish important from less important parameters? Using just syntax blocks can be really hard and emphasizing mandatory parameters would really help. For example, a simple command Get-Job has 12 parameters and 6 different sets. How long it takes to identify mandatory parameters from these syntax blocks?

screenshot 1

Taken from https://docs.microsoft.com/en-us/powershell/module/Microsoft.PowerShell.Core/Get-Job?view=powershell-5.1

I have noticed also that docs.microsoft.com started using colouring for mandatory parameters in syntax blocks. That is nice and helpful, but unfrtunatelly not compatible with markdown or console output. Also, it is not fully persistent, some mandatory parameters are not emphasized.

screenshot 2

Taken from https://docs.microsoft.com/en-us/powershell/module/Microsoft.PowerShell.Core/Get-PSSession?view=powershell-6

[sdwheeler]

@iricigor Interesting. I had not noticed that highlighting behavior before. The highlighting is there because the syntax block is identified as a PowerShell code block in the markdown for Get-PSSession. That is not the case for Get-Job. Across the docset we have a mix of syntax blocks unmarked and marked as "PowerShell". In our style guide we have decided that syntax blocks should be unmarked because they illustrate the syntax but do not represent usable PowerShell code as shown. Ideally, it would be nice to have highlighting code that understood the syntax blocks and could highlight the mandatory elements.

[vors]

@sdwheeler yes, thank you for including this guideline!