Improve inconsistent help messages of some specific commands

[LronDC]

What would you like to be added: follow-up #117930 I opened a PR #117930 to optimize help messages' usage line behavior. In the process I also optimized kubectl create secret --help description from

Create a secret using specified subcommand.

to

Create a secret with specified type.

 A docker-registry type secret is for accessing a container registry.

 A generic type secret indicate an Opaque secret type.

 A tls type secret holds TLS certificate and its associated key.

After @brianpursley 's careful review and a little discuss, I found the following issues：

• kubectl create service --help may also be too simple, and I think it should be enriched a little.
• Except kubectl create secret that I've optimized, there are also create service plugin rollout set top whose usage line showing "kubectl xxx [flags] [options]". IMOP they should be like kubectl xxx (subcommand1 | subcommand2 | subcommand3) [options] in an enum style or at least kubectl xxx <command> [options].
• rollout and set behaves differently than other commands: "kubectl xxx SUBCOMMAND [options]", I think it should be consistent with others.

Significant changes like "command description" or "help message consistent style" may better be decided on by SIG. So I'm following @brianpursley 's suggestion to open this issue to discuss about this.

Why is this needed:

Clean up messy and inconsistencies is never a bad thing :).

[Ritikaa96]

I was working on help output of explain when I noticed the same inconsistency Especially:

• IMOP they should be like kubectl xxx (subcommand1 | subcommand2 | subcommand3) [options] in an enum style or at least kubectl xxx <command> [options]. If it is in the discussion, making it an umbrella issue might be helpful.

[Ritikaa96]

In case it is open for contribution, I'd be glad to help add these improvements.

[LronDC]

In case it is open for contribution, I'd be glad to help add these improvements.

That's great! I also have done some work on the command that I mentioned. We can evaluate and merge our work if there is a need. But I haven't heard any suggestions from the SIG yet. SIG's opinions are important here I guess.

[Ritikaa96]

That's great! I also have done some work on the command that I mentioned. We can evaluate and merge our work if there is a need.

Sure thing. I would say making it an Umbrella issue would be better as there are lots of commands help messages that needs to change in this way.

But I haven't heard any suggestions from the SIG yet. SIG's opinions are important here I guess.

I'd agree , I'm waiting for sig experts to share there thought. we should not start working on this until the triage is accepted and until there is a discussion done on same topic.

[mpuckett159]

/triage accepted If there are still things to fix under the umbrella of this issue we can leave it open, if not we should close it.

[LronDC]

If there are still things to fix under the umbrella of this issue we can leave it open, if not we should close it.

Yes, there are still things to fix

I was working on help output of explain when I noticed the same inconsistency Especially:

• IMOP they should be like kubectl xxx (subcommand1 | subcommand2 | subcommand3) [options] in an enum style or at least kubectl xxx <command> [options]. If it is in the discussion, making it an umbrella issue might be helpful.

We need to decide on a style to fix it.

[mpuckett159]

Oh yes. Did we discuss this at the last biweekly meeting? This would be a good topic for that meeting.

[Ritikaa96]

I'd love to have a discussion about it as well The help messages have some inconsistencies that can use a fix.

[LronDC]

Oh yes. Did we discuss this at the last biweekly meeting? This would be a good topic for that meeting.

I did not attend the last meeting, so it probably hasn't been discussed yet.

[Ritikaa96]

Update on the same,Two related issues are : #1452 #1457

[LronDC]

I apologize for may not be able to focus on this recently. Once I'm free I'd love to work with you @Ritikaa96. Unless you're so efficient I can't catch up. 😆

[Ritikaa96]

Sure, I end up finding this while working on something so let's see if we can catch all the commands with inconsistencies.

[brianpursley]

I haven't been following this issue, but since I'm mentioned a couple times because of my original comment on another PR that prompted this, I want to add some points to the discussion. These are my opinions, for what it's worth...

I am for fixing mistakes and adding clarification that help users understand and use kubectl better.

However, I'm not so sure that all help text needs to be updated across the board. I guess I would want to see the kind of changes being proposed first.

I think we should avoid only updating the style without improving the substance of the help, as that doesn't really add a lot of value to the end user.

So in summary: fixing inaccuracies and clarifying usage is good, but only rewording things should be avoided.

[Ritikaa96]

fixing inaccuracies and clarifying usage is good, but only rewording things should be avoided.

Hi @brianpursley , Thanks for clarifying the stand on this. There are some help messages that will still need some change. For eg .

• kubectl plugin command doesn't have example, `
• kubectl get --help states the following even though we can use --namespace to get details for other namespace resources.

  • You can filter the list using a label selector and the --selector flag. If the desired resource type is namespaced you will only see results in your current namespace unless you pass --all-namespaces.

• Usage kubectl replace -f FILENAME should be more elaborate as we can also add customize directory so rightfully ::
  • kubectl replace ([-f FILENAME] | [-k DIRECTORY])
  • This is missing in most of the help messages.
• There is inconsistency of Resource name being mentioned as either RESOURCE or TYPE. that needs to be solved.
• kubectl diff --help can have more examples

[Ritikaa96]

Raised two issues related to this one : #1554 , #1555