Docs: Command samples vs. shells

[waldekmastykarz]

In her PR #2167, @LuiseFreese brought up a good point that the command samples we show in our docs assume that you run them in *sh shells. When you try to use them with PowerShell, you get errors because PowerShell expects values to be enclosed in " rather than '.

How should we handle it to give our users the best experience? Using " would probably work on any shell, but it decreases readability of the examples due to escaping. On the other hand, it gives our users ready-to-use code.

What do you think @pnp/cli-for-microsoft-365-maintainers?

[plamber]

We should indeed have a look in the example section and make it as simple as possible in these cases. The way you fixed it in that PR might work fine but adds more text to the output. I would change the organization of samples differently. Rather than having a separate section with PowerShell we should think about adding both examples under one hood. Maybe something like that:

This is your awesome script
PowerShell: m365 cli ...
Other shellls: m365 cli ...

We might need to revisit the way we handle the output overall

On top of this, I believe we have to revisit the way we are outputting the help. Scripting with Windows PowerShell or the ISE feels clumsy and is sometimes unreadable.

Windows Output in PowerShell 7:

Windows Output in PowerShell ISE:

I see more action items here:

• The formatting of the scripts works differently in different shells -> We might need to simplify the way we are formatting the help
• The experience while writing scripts does not feel right. I know I brought this already up. I think it makes sense to bring this up in this conversation too.

How is it solved by others?

The Azure CLI Way

I enjoy writing scripts in the Azure CLI because it does not disrupt the flow when writing scripts. I still have hard times when making a typo during script creation. I am getting back the whole help with examples as default behavior.

When something goes wrong

• Error message in red and a hint how to get help
  If I am really stuck it just costs me to add a --help output.

Do you need help?
az vm --help

• It outputs just the parameter list and tells you to use a different command to get examples

Do you want examples?
az find 'az vm'

• It just outputs the examples to the user
• The output is kept simple. Examples separated by one empty line; bold title; normal text for the example. This has less formatting issues in consoles with different colors.

The PowerShell Way

PowerShell has a dedicated command to output the help. What a like here is that they are also separating the core information of the command from the examples.

Get-Help Format-Table -Detailed
Get-Help Format-Table -Full

How would I improve the current situation?

• Step 1: Fix the formatting of the help command first. Keeping it simple without special formatting.
• Step 2: Take the way the Azure CLI is outputting when something goes wrong. Just error message and hint how to get help if required. This will definitely improve the flow when writing scripts
• Step 3: Think if it makes sense to have a separation of specs and examples like PowerShell or the CLI is doing to have a shorter output when getting help. Maybe introduce a new command extension --examples that outputs the examples and keep --help for the command specs

[waldekmastykarz]

You're bringing up valid points @plamber. I converted the issue into a discussion so that we can more easily discuss the different topics you brought up and can create related issue once we agree how we want to handle them. Let's start a separated thread for each issue you brought up.

[waldekmastykarz]

Step 1: Fix the formatting of the help command first. Keeping it simple without special formatting.

We should check how our help is rendered across the different terminals and shells. If the current rich format isn't helpful, we should definitely simplify it. Having comparable samples (shell vs. terminal vs. OS) would help us understand the differences and move forward.

[waldekmastykarz]

For me, shrinking the ISE window has no effect. I'm getting a horizontal scrollbar but the content looks the same.

[waldekmastykarz]

I've tested it btw on a vanilla win10 VM where the only extras are Windows Terminal, Microsoft PowerShell and CLI installed

[plamber]

Then it just does not work on my end. Is maybe an issue with resolution and size settings 🤔

[StfBauer]

I created an issue on Markshell - It all comes down to the EOL handling of different consoles. Will try to fix those this week -StfBauer/markshell#26

Thank you for letting me know.

[waldekmastykarz]

Awesome! Appreciate your help @StfBauer ❤️

[waldekmastykarz]

Step 2: Take the way the Azure CLI is outputting when something goes wrong. Just error message and hint how to get help if required. This will definitely improve the flow when writing scripts

We've discussed this previously and after asking the community we decided to make it configurable. This will become available when #2146 is merged.

[plamber]

Can we configure with this setting also a default output? I would find it useful to set the output to be always json when writing scripts.

[waldekmastykarz]

Definitely and a great idea! Once #2146 is in, we can introduce all kinds of configuration that will allow people to configure CLI to their personal preferences.

[waldekmastykarz]

Step 3: Think if it makes sense to have a separation of specs and examples like PowerShell or the CLI is doing to have a shorter output when getting help. Maybe introduce a new command extension --examples that outputs the examples and keep --help for the command specs

Since it would be a breaking change, we could consider it for v4. Before we decide whether we should do it and how, we should have a look at other tools. Like you mentioned, PowerShell has a standardized way of doing it. But CLI for Microsoft 365 is not a PowerShell module and can be also used on other shells that might not share the same philosophy. So before deciding on a solution, let's have a look at other CLIs and how they handle that.

[plamber]

I see that PowerShell and the Azure CLI are separating examples and "classic" help.
When scripting I typically use the "examples" output more than the "classic" help to get fast up-to-speed.

I would prefer just outputting either one of both sections. The output is smaller (which is good in smaller windows) and I am focusing on the specific information I am interested in.

[waldekmastykarz]

It would be interested to get input from others on this topic. The approach you mentioned is typical for PowerShell but I haven't seen it in any other cross-platform CLI out there. Since CLI for Microsoft 365 can be used in any shell, we should see what's intuitive for all our users. One idea could be to make this configurable so that you can specify if by default you want to get only short help without examples or full one. That could allow us to accommodate personal preferences without enforcing a particular style on anybody. Would that work?

[LuiseFreese]

Letting people choose how they like it will give more people a good experience than defining that for them based on own experiences or guessing.

[plamber]

The configurable option is definitely the way to go.