And no man page

Reminds me of a comment I once came across in a work application's code: "This function took forever to write correctly. It was hard work. I didn't document it. Figure it out."

Of course the variables were not defined properly and were named esoterically.

the variables were not defined properly and were named esoterically

I wonder why it was so hard and took so long to write
- Poor skill, mostly.
At what point is documenting decompiled code easier?
Me: "haha...no" proceeds to delete function "whoever wrote this can figure it out again."

$ mysterytool
$

WHAT DID YOU DO?!

$ mysterytool -vv DEBUG: Complete. $
Knowing my luck, It probably deleted a rarely used system library and will lead to unpredictable crashes.

I don't understand how devs can be too lazy to write documentation but somehow they'd rather explain the same shit in discord over and over and over and over and over and over

The help command is one of the first things I work on in any project. Even if I'm never gonna share it, my future self will appreciate it.
- Even on simple scripts, it's so help to remind yourself however the hell you made it work.
- I always document a lot because I forget what I was doing one week after.
Why is discord so popular in non-gaming circles? People use it as a shitty, bloated and centralized IRC clone, with the voice fuction being completely ignored.
- bc everyone is a gamer, and using another chatting app is just adding more clutter
- I'm no discord fan but my recent attempts with using IRC failed because I had incorrect reverse dns or some shit like that. Obviously I have no control over that in a consumer connection.
  
  There are still better alternatives than Discord, though :)
i write poorly documented code on my solo projects because i am lonely
- I write buggy software so that users will email me.
Easy: people who still use Discord have brain rot
- Why?
I think it's loneliness, honestly.

That and corporate work environment tends to rewards those that can explain stuff vocally ad nauseum.
As someone who writes fairly extensive documentation, I can assure you that it doesn’t matter. People will still ask questions in your Discord that are answered in your documentation.

I’ve learned that you kind of have to strike a balance between being terse enough that people will read it and verbose enough that it’s actually helpful, but there is a minimum number of questions you will always get.
At work, I am one of the few who actually documents. Not only with Doxygen, but I also write real documents regarding all kinds of topics.

Guess what? "I know you have this documented somewhere, but could you just quickly explain again how this common task works?"

I was recently trying trying to get help on a clipboard program someone had recommended me, clipq. What I found instead was a GitHub discussion where the dev said "I'm not sure what you mean by 'man' pages" in response to someone asking for them. I think I need to find an alternative

Did they at least provide woman pages then?

/s
I've only known about (and always use) xclip.
- copyq — if anyone needs universal multiplatfom gui app
Be the change you want to see in the world and create a PR. 😃
tbf syntax for writing manpages is closer to latex than markdown
- It is not that complicated and there are plenty of tools to generate man pages from other formats. Besides, this is about the dev not knowing what a man page even is.
Soy devs have invaded Linux.
- What do you mean by this?

Haha, I made this :) Here’s the blog post I created it for, if you want a bit of context:

https://www.tweag.io/blog/2023-10-05-cli-ux-in-topiary/

Correct, I shamelessly stole it!

Also, sorry, I stole it.
- No worries :)

But also

mysterytool --help
mysterytool: unrecognized option: '-'

ok then...

mysterytool -h
mysterytool: unrecognized option: 'h'

mysterytool --help ‘--help’ unrecognized option, -h for help

I will burn this motherfucker to the ground
- Or the opposite:
  
  mysterytool -h -h unrecognized option, --help for help
  
  Both need to burn.
And

mysterytool -h

mysterytool: try our info page that requires a custom viewer because gnu is better than standards. And there is no regular man page because fuck you
- If I can't get it with tldr mysterytoolafter all that, then clearly the developer intended it to stay a mystery.
- It could be worse. The documentation could be online, only accessible through a paywall.

If the program's author hasn't bothered to properly document its function, then it has no business being on my machine.

"tHe PrOgRaM iS sElF dOcUmEnTiNg"
- That claim doesn't even work for the 0 line shell script that used to be /bin/true (which is why it is no longer a 0 line shell script), much less any more complicated program.
- Fuck those people, people who says that usually doesn't even understand half the time. When I ask people like that when they write a functionality a certain way during code review usually they'll just quote someone on Twitter or some blogspam article saying A is shit, B is the best way to do things.
I'd pretend to be Joey from Hackers and just throw commands at it to see what happens. Maybe I'll make an ATM in bumfuck, Egypt spit out hundreds of dollars or find a worm in a garbage file 🤷🏻‍♂️
- Hack the planet!
If it is open source, you can read the source...
- Or he can waste less time and download a properly documented open source tool.
- Only if the source is structured and has readable names. Spaghetti code with made up variable names that only the programmer knows the meaning of (or may not even remember what they mean at all) isn't that much better than combing through the disassembled machine code.
- Which is fine for a.small and simple tool. But I have seen massive graphic/UI libraries with a documentation of about two pages and a non-working example.
  
  Worst offenders I have to deal with is mediawiki. Some random hacker replaces some code with his own, and immeditely obsoletes the previous code that worked absolutely fine. The new code might work, too, but the concept, the philosophy is 100% different that the old interface. So e.g. the old interface made a call with 10 or 20 parameters, the new one makes a ton of calls of the type "add one or two parameters to an object".
  
  And of course the only documentation is just the excrement of a Doxygen call. Where nobody ever cared for the function description headers in the source.
  
  My "favourite" one is a function with a parameter named "options" and a description as "option flags". Nothing more. And the source of the function? Well, I have seen staighter spaghetti dinners.

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.
- 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)
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

It's like people don't like surprises anymore.

Embedded *nix be like

Cries in busybox
- That, at least, had an excuse to be terse. If you use busybox, you probably have a real machine with the ability to browse the online documentation, anyway.
Legacy *nix vendor tools be like

Exclusively installed through some dodgy PPA you got from a blog.

strings `which mysterytool` | less

Give up your darn secrets before I start fumbling around with strace and get even more frustrated!

I just want to say this is a masterful use of the format.

I'd try mysterytool -H

-H for Hard drive to delete, -h is help
- -H is for Hforce
- -h is halt.
- -H is for "hell no just uninstall"
  
  Look, if they can't stick to established convention and they're not gnu (and thus magically excusably arrogant as fuck because #stallman), then you just know they'll be somehow dragging in remote libraries or something equally as fuckwitted; so just remove it and live your life.

find / -name mysterytool -exec rm {} \;

rm $(which mysterytool)?
- What if that returns just an alias?
  
  But really the best way would be first to try one's distro manager to uninstall/purge the package. Unless it was just manually installed by the user.
  
  Oh, maybe that's it! It only exists in ~/bin, and OP is having a psychotic break, is just now finding out about their split personality!
Y u no -delete
Use +; \; is for peasants.