this post was submitted on 12 Oct 2023
1268 points (98.5% liked)
linuxmemes
21393 readers
1257 users here now
Hint: :q!
Sister communities:
Community rules (click to expand)
1. Follow the site-wide rules
- Instance-wide TOS: https://legal.lemmy.world/tos/
- Lemmy code of conduct: https://join-lemmy.org/docs/code_of_conduct.html
2. Be civil
- Understand the difference between a joke and an insult.
- Do not harrass or attack members of the community for any reason.
- Leave remarks of "peasantry" to the PCMR community. If you dislike an OS/service/application, attack the thing you dislike, not the individuals who use it. Some people may not have a choice.
- Bigotry will not be tolerated.
- These rules are somewhat loosened when the subject is a public figure. Still, do not attack their person or incite harrassment.
3. Post Linux-related content
- Including Unix and BSD.
- Non-Linux content is acceptable as long as it makes a reference to Linux. For example, the poorly made mockery of
sudoin Windows. - No porn. Even if you watch it on a Linux machine.
4. No recent reposts
- Everybody uses Arch btw, can't quit Vim, and wants to interject for a moment. You can stop now.
Please report posts and comments that break these rules!
Important: never execute code or follow advice that you don't understand or can't verify, especially here. The word of the day is credibility. This is a meme community -- even the most helpful comments might just be shitposts that can damage your system. Be aware, be smart, don't fork-bomb your computer.
founded 1 year ago
MODERATORS
you are viewing a single comment's thread
view the rest of the comments
view the rest of the comments
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.
I never understood that. I'm a programmer and I tend to over-document.
the messiah
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.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.
Morgan Freeman: "But they didn't"
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.
The point is that a programmer would first need to think about what needs to be explained or not to the average user and then explain it properly, none of which is considered as interesting as coding.
It's not by chance that even tools with actual one line of explanation for each parameter are general of the badly documented kind (I especially like the ones were the "help" for a command doesn't say what the bloody command actually does).
I mean, you even see this kind of meaningless "documentation" in API documentation for widelly used libraries were the documentations is generated from comments embedded in the code: "public void doStuff(int height)" => "Does stuff. Parameters - height: the input height".
I might have put it in a humouristic way but this quite a well-known and widespread phenomenon.
No idea why'd anyone would do this if they expected anyone besides them to use their tool.
Even I myself am not gonna remember how to use my tool a couple months down the line, unless it's something I use very regularly.
Edit: noticed I read the comment I'm replying to wrong, reworded to make more sense