Add filter flag documentation and examples to help message

[glrf]

The Hubble CLI provides multiple different flags to filter the returned
flows. However how these filters are combined is not entirely obvious.

This commit adds more detailed help message and multiple examples that
explain how these filters interact if more than one filter flag is
provided.

I struggled to make this concise and understandable, so I added more detailed examples. I'm happy about any input to improve this and make it clearer.

[maintainer-s-little-helper]

Commit 03677e3 does not match "Signed-off-by".

Please follow instructions provided in https://docs.cilium.io/en/stable/contributing/contributing/#developer-s-certificate-of-origin

[chancez]

Overall a good improvement. I left some comments around grammar and terminology that should be updated as well. My only concern is this is making the already really long --help even longer, but I think this is fine.

[glrf]

My only concern is this is making the already really long --help even longer, but I think this is fine.

That's a fair point. The help message is very long now. If this grows even more, it might be a good idea to move the examples to the docs.cilium.io and just link to them in the help message?

[chancez]

@gandro @kaworu any thoughts on if we're okay with adding some more usage examples to the help test?

[gandro]

@gandro @kaworu any thoughts on if we're okay with adding some more usage examples to the help test?

Yeah, I'm also a bit worried about help page length. On the other hand, I do think those examples brings a lot of value to users who are calling hubble observe --help for the first time. And I think having it displayed to users when they are actively looking for help is a nice way to discover it too (since we have to assume that many people will not read or find the docs as quickly as they will try --help).

It's mostly users who already know the basics of Hubble for which this adds a lot of visual clutter, making it harder to quickly look up the reference for a flag they are looking for.

Maybe an option would be to maybe have short and long help flag? That I think would cover both cases: Users who are learning Hubble and want a more verbose help page, vs. users who just want to quickly know about the syntax or name of a particular flag.

[kaworu]

Thanks @glrf! Couple of typos and nits on the way.

Overall LGTM, agree with @gandro that a short and long help would be best.

[glrf]

Thanks for all the input on the help text. I often struggle with technical writing so I'm always happy about feedback.

And about the short and long help flag. I think I agree that this sounds smart, but when I actually tried to implement this I struggled to find a clean solution. I can see three ways of doing this and all three have pros and cons

• Make -h,--help the short help flag and introduce something like --long-help or --detailed-help or --explain that shows the long help text. The disadvantage here would be that new users might just not see it. Similar problem to moving it to the docs and linking.
• Make -h,--help the long help flag and introduce something like -b,--brief-help or mabye --ref(for reference? Or IDK naming is hard). The disadvantage here is that most people will likely just continue using -h and live with the clutter, as they're just used to it.
• Make -h show the short help text and --help show the long help text. I could make this work, but it felt like a hack and I don't know if that's too magical and will confuse users.

Any opinions?

[chancez]

Another alternative is a new sub-command like hubble observe usage-examples or something?

I'm personally okay with updating the existing --help and then we can always follow up with another PR to move the usage examples out of the --help and into somewhere else.