Modify help output in case of error

[Adam-it]

This issue is a follow up form the #5182. Let's discuss here if and how we could adapt the help mode output in case of error. In the related issue @martinlingstuyl suggested that the printed help in case of errors only shows the description of the command, combined with a message about how to get the full version. This is an interesting idea for maybe a totally new help mode we could support.

Specs

In case of errors we currently show the help page. This issue is about changing that to a single line of text that instructs the user how to get help:

Run (command name) -h for help.

The current command should be included in the message. For example:

Run 'm365 spo site list -h' for help.

[Adam-it]

@pnp/cli-for-microsoft-365-maintainers any feedback regarding this idea?

[waldekmastykarz]

My main argument against this change is that it doesn't help the user recover. It seems like we suspect that users will need to access full help, so we want to include instructions how to do it, but then, why not do it directly ourselves?

I suggest that we think this through some more, considering the different configuration options that we offer and how they'd work towards addressing our users' needs.

[Adam-it]

My main argument against this change is that it doesn't help the user recover. It seems like we suspect that users will need to access full help, so we want to include instructions how to do it, but then, why not do it directly ourselves?

I suggest that we think this through some more, considering the different configuration options that we offer and how they'd work towards addressing our users' needs.

I say we don't change it and leave it as is. @pnp/cli-for-microsoft-365-maintainers any other comment before I close it as not planned?

[milanholemans]

It seems like we suspect that users will need to access full help, so we want to include instructions how to do it, but then, why not do it directly ourselves?

Full help can be useful indeed. However, I've already had several people come to me saying "I ran a command and it just printed a bunch of text, why?", not noticing the error above the help page. This is the only thing I don't like, it has become difficult to read/notice errors.

[Adam-it]

@milanholemans wont this change a bit if now the default help option is option not full ? What do you think?

[martinlingstuyl]

I think it helps a bit, but even the options mode prints quite a long piece of text.

I agree with @milanholemans on this and still feel that we should print a very minimal message (with instructions to get the full) by default when people run into errors.

The point is that you want to give people a helicopter view: the clean error and the way to possibly get help. They'll decide themselves if they want more details.

It communicates enough and people would know where to find the help and are not blocked because we print a lot of text unasked for.

[Adam-it]

It's a hard call. As if someone is new with CLI then he or she will for sure want to check the help anyway. On the other side if someone is already an advanced user then he or she would like to see only the error message I guess. I wonder if the other will just change the output setting 🤔

[milanholemans]

Like @martinlingstuyl said, right now people are mind-blown with the whole help page we throw in their faces. They are not noticing the error message on top of the output. As mentioned before I've had a bunch of people reaching out to me. They didn't understand what happened. I like the idea of letting them decide whether they need the help page or not. We can just print the error and tell them, if you need help, do this.

Printing the entire command page isn't always that useful. Most of the time, the error is clear enough especially when it's a validation error from the CLI.

[Adam-it]

gotcha 👍. After reading this I get your point. What if we together with printing the error and only the start of the help (or any other short form of the help page) we also add info on how to enable it by default to always print the full help page? I totally understand (I think) this improvement. I am only afraid that for new folks we will introduce and additional step to show the help page anyway 🤔.

@waldekmastykarz could you double check @martinlingstuyl and @milanholemans comments. What do you think?

@pnp/cli-for-microsoft-365-maintainers any other feedback?

[waldekmastykarz]

If we don't want to show any additional information in case of an error, can't this already be done by configuring showHelpOnFailure to false?

[milanholemans]

Yes, the problem is that new/inexperienced users don't know this. They just see their screen being flooded with text and they have no idea that they encountered an error.

[martinlingstuyl]

Yeah, so the point is the default behavior should point towards using the help, but not force it down your throat. Disabling it by default would not be preferred behavior. Showing a minimal pointer would in my opinion. You can discuss about what the minimal pointer contains, but at the least it should be minimal...

[waldekmastykarz]

Alternative idea. What if:

• we don't show help by default
• instead, by default, in case of an error we show something like: run (command name) -h for help

If you made a typo that you can easily fix, you don't get a wall of text. If you need help, you know how. You don't get to see help that's not helpful (ie. too little information).

[martinlingstuyl]

This is the kind of thing we're talking about @waldekmastykarz. Excellent idea. I don't care what's shown, as long as it's short and points the user to how he can get help.

[waldekmastykarz]

Seems like we've gone full circle 😄

[milanholemans]

Yes, that would be nice in my option. The user decides whether he/she needs help or not. When you make a typo or the command validation fails, it's not always useful to see the entire help page being printed. An error message like The option id is not a valid GUID. is clear enough I guess. It doesn't need the help page to be printed.

[martinlingstuyl]

Let's get this shipped! 🚢

[martinlingstuyl]

Could you verify the specs @milanholemans, @waldekmastykarz, @Adam-it?

[milanholemans]

Grammar police, let's start with a capital letter and put a period at the end 🙂

E.g. Run 'm365 spo site list -h' for help.

Other than that, looks good to me!

[Adam-it]

Grammar police, let's start with a capital letter and put a period at the end 🙂

E.g. Run 'm365 spo site list -h' for help.

Other than that, looks good to me!

I share the same opinion. thanks @martinlingstuyl, @milanholemans, @waldekmastykarz for the awesome brainstorm along the way 👍 you rock 🤩

lets open this up

[MathijsVerbeeck]

Can I work on this?