Actually the first should be the latter, not in the sense that there shouldn’t be a list of switches, a list of options somewhere, or no terse sum-up docs for all those little things, but that those sum-up docs should be the header to a guide.
I may be getting old but I think earlier UNIX had that, and we kinda lost it: Back when programs had few switches the man page would have a header explaining the command tersely – “foo grobnitzes flobboxes” or such, two or three options described equally terse, then you’d get into usage and examples. Nowadays, where GNU less lists its options as
, note the fucking alphabet in the beginning, it’s pages upon pages of terse technical definitions in the rest of the manpage. (Yeah I know less probably doesn’t need extensive usage docs it’s pretty self-evident but my point stands).
We have hypertext now. This can contain a gazillion links to this. And please no no gnuinfo I still don’t know how to navigate that thing, I barely know how to exit it. Lynx and w3m prove that it’s possible to do intuitive design with links in the terminal, do better. Me wanting to quickly look stuff up is not the right time to insist I learn your awkward pet documentation interface, Richard.
You are not logged in. However you can subscribe from another Fediverse account, for example Lemmy or Mastodon. To do this, paste the following into the search field of your instance: !programmerhumor@lemmy.ml
Post funny things about programming here! (Or just rant about your favourite programming language.)
Rules:
Posts must be relevant to programming, programmers, or computer science.
No NSFW content.
Jokes must be in good taste. No hate speech, bigotry, etc.
Not even a forum.
Documentation is not a snapshot of a discussion. It largely falls into two categories
The first is vital. The second is really really useful.
Actually the first should be the latter, not in the sense that there shouldn’t be a list of switches, a list of options somewhere, or no terse sum-up docs for all those little things, but that those sum-up docs should be the header to a guide.
I may be getting old but I think earlier UNIX had that, and we kinda lost it: Back when programs had few switches the man page would have a header explaining the command tersely – “foo grobnitzes flobboxes” or such, two or three options described equally terse, then you’d get into usage and examples. Nowadays, where GNU less lists its options as
, note the fucking alphabet in the beginning, it’s pages upon pages of terse technical definitions in the rest of the manpage. (Yeah I know less probably doesn’t need extensive usage docs it’s pretty self-evident but my point stands).
We have hypertext now. This can contain a gazillion links to this. And please no no gnuinfo I still don’t know how to navigate that thing, I barely know how to exit it. Lynx and w3m prove that it’s possible to do intuitive design with links in the terminal, do better. Me wanting to quickly look stuff up is not the right time to insist I learn your awkward pet documentation interface, Richard.