Programmers generally detest to do documentation, so when the user help “UI” is all down to a programmer to define this is often what you get, especially if it’s a small tool.
Yeah this is shitty, and if you’re a programmer reading this and you agree with it, be better. There is no excuse for under-documenting a CLI.
Even when I’m developing, I write out my usage text first, like -o [json,csv,pretty] specify output format (default 'pretty') [NOT IMPLEMENTED] or the like.
If you use something like Rust’s clap --help output is very easy to add, all you need is basically a single line comment for each option.
Oh, you sweet summer child, there is no level of ease for the average programmer that will make him or her want to document things… ;)
On a more serious note, good documentation for parameters in any tool that’s not stupidly simple tends to be more than a one liner if one doesn’t assume that the user already knows a ton of context (for example, imagine explaining “chmod” parameters with just one liners)
You can write more than one line but one line is usually enough for each of the options in the --help output. Obviously that doesn’t explain everything and especially not background like “how do unix permissions work” in your example but the --help output is not the correct place for that kind of information anyway.
No idea why’d anyone would do this if they expected anyone besides them to use their tool.
Speaking for myself a long time ago when I was younger and handsomer but dumber ;) some people at a certain stage of their lives have trouble remembering that what’s obvious for oneself given the context one is in and the information one has, is not obvious for others.
I like to think most of us grow out of it.
