Reorganized help text some, grouped option flags #3
Conversation
| }, | ||
| cli.StringSliceFlag{ | ||
| Name: "out, o", | ||
| Usage: "Write all measurements to a database", |
There was a problem hiding this comment.
Inconsistent wording: measurements vs metrics above.
There was a problem hiding this comment.
That was by design actually - to show that we log actual, collected measurement samples to influx, rather than the calculated metrics that are logged to stdout. But I'm open to alternative ways of expressing the distinction.
There was a problem hiding this comment.
Do we really need to express that difference? Technically, the tags are applied to samples, which form metrics (which we log to stdout or stream to a database). The distinction doesn't really seem to matter here…
"Write metrics to a database" seems like it'd convey the same message more concisely.
There was a problem hiding this comment.
I think it is important to understand that the data sent to influx != the data sent to stdout. If we just say that "metrics" can be sent either to stdout or influx, people will expect the data to be the same and that --select or --exclude applies to both. I thought about using another header name instead of "OUTPUT OPTIONS", like perhaps "STDOUT OUTPUT OPTIONS", which would highlight the difference.
There was a problem hiding this comment.
Ah, I see. I think we should go about this another way.
The data sent to influx is the same data that is sent to stdout, or any other destination we may add in the future. In either influx/Grafana or stdout, you can filter the data being presented to you, but it doesn't change the underlying dataset.
How can we communicate that --select, --exclude and --group-by change the presentation of the data on stdout, rather than pointing out how --tag and --out (which work on any destination, not just stdout) differ from them?
There was a problem hiding this comment.
Well, my simple solution was to put them in a separate group/section, with a header. Another way would be to stress in their descriptions the fact that they only filter stuff sent to stdout (which would probably use up more characters than using a group header). A third way would be to rename them to something that sounds a bit less generic. --stdout-select, --stdout-exclude, --stdout-group-by (not suggesting those, just making an example).
|
I really don't like the idea of having the options split like this. I'd prefer if the logical grouping and descriptions could be used instead. |
| Usage: "Suppress the summary at the end of a test", | ||
| cli.DurationFlag{ | ||
| Name: "interval, i", | ||
| Usage: "Write periodic summaries", |
There was a problem hiding this comment.
Hm, I know I wrote this one and all, but I actually wonder if it could be made clearer. It doesn't really indicate that you should pass in a duration.
|
What do you mean by "the logical grouping"? |
|
As in, the order they are presented within the singular list, putting related options next to each other. |
|
If we don't want to use groupings/sections, many tools have other ways to get more info in about options. Locust uses multiple description lines for each option (locust --help). I saw another tool that inserted example command lines in between option descriptions, but I can't remember which one. Some examples of grouped options include Httpie - https://github.com/jkbrzt/httpie, Wget or Salt (Saltstack). Httpie is considered a lot more user-friendly than curl (which uses the docker run --help style help text). |
|
I'm just gonna close this while we go ahead and add subcommands. That should eliminate a lot of potential for flag bloat. |
No description provided.