The idea that manuals in linux are a good way to learn and understand new software is peak linux neckbeard bs, and I will die on this hill. I congratulate OP on the exact type of autism that lets them feel this is an effective and useful method for learning new software, but if there is desire to have a greater adoption of linux maybe its bad to be snarky at folks for not instantly understand the terminal based documentation conventions of some dudes in the 70s. Maybe an alphabetical* list of all possible options is okay for referencing or searching, but is objectively insane way to learn or understand a problem.
initially when I was learning linux. I had troubles finding the command I needed. I could have first gone and read everything and then come back to try, which I did. But sometimes the man pages, the ubuntu and arch forums weren’t as great of a help as messing up myself.
Could there be a better way to document with slightly more examples: yes. Would it help: tons
as a professional sociotechnical problem solver I will join you on this fatal hill
like take the 4 types of documentation in diátaxis
man pages usually fulfill the reference need, and sometimes kind of that of how-to guides if you’re lucky and your local man has examples
but that leaves more than 50% of documentation needs lacking
and discoverability is atrocious – you have to already know that the command (or commands) you need exists and what it’s called
one of the most useful things I learned in a linux sysadmin course was apropos / man -k, which lets you search installed man pages by keyword. but hardly anyone else seems to know about it – I only learned of it because a teaching assistant mentioned it off hand! – and even then it only helps if you guess the right keyword for your problem
I think it should be the default if you don’t use parameters. A little usage help and the list of commands (with a “do you want to see the list of commands? (Y/n)” message)
There’s other ways to get info. And man pages are a great way to learn how something is expected to work on your system. And it’s offline, without ads, scams, ai generated false info.
THIS. I feel like linux man pages are as useful as an Analytical mechanics textbook for someone who just wants to drive. Like yes, sure, it’s amazing we have such a detailed documentation but for God’s sake just introduce basic usages first
ssh connects and logs into the specified destination, which may be specified as either [user@]hostname or a URI of the form ssh://[user@]hostname[:port]
That’s how I would interpret that part of the man page had I no familiarity with ssh. It doesn’t seem reasonable to expect the reader to know what those brackets mean.
You get to learn the notation conventions with <> and [] fairly early on. Maybe a very new user would make that mistake. If he doesn’t get it fairly quick, maybe computers aren’t for him.
You might be thinking of info pages. The man pages are just the instructions, feature flags, etc. generally, while info (when available) usually has a more general / layman description of the command with examples.
Hrm, I checked the manpage for grep on my Mac an there are a number of examples. I checked it on Linux and there’s one example. I must be spoiled by the BSD’s.
It’s a good thing there are other resources, then. You can read tldr-pages. You can look at various official and unofficial wikis. You can look at Stackoverflow. You can look at Youtube tutorials. You can ask other people. Hell, you can ask a chatbot.
If the average user is unwilling to do that, maybe it’s better that Linux does not see a wider adoption.
is the fact that people can with effort and error figure out how to do something a reason not to make it easier for them to do?
I mean
you can in theory write multi-threaded bug-free C code – just read the docs and the specs and the source of your libs and never ever do something that seems to work but is subtly fatally incorrect
and yet we still have golang and rust and many other options to do things more safely and easily
if someone wants to use Linux but doesn’t want to memorize the Hundred Mandatory Commands and Thousand Flags lest they accidentally cat > /dev/sda, why shouldn’t there be a system for them?
The community abhors change. Especially changes that break conventions, even informal ones. Look at the temper tantrums people are throwing because Wayland does things differently from X.org. Changing output redirection in Bash, or how dd works, or any number of long-standing conventions because new users are unwilling to adapt to a new system and might end up dding over the root partition would break established workflows, and worse, existing scripts and services.
But the solution already exists, it’s called wrapper programs. You don’t have to manually update AUR packages because yay and paru already do that. You don’t have to figure out how fdisk and mkfs work because Gparted and Partition Manager do it for you.
Nevertheless, using a system should always and forever be the user’s responsibility. Otherwise Linux would turn into a locked-down play pen like Apple products.
The idea that manuals in linux are a good way to learn and understand new software is peak linux neckbeard bs, and I will die on this hill. I congratulate OP on the exact type of autism that lets them feel this is an effective and useful method for learning new software, but if there is desire to have a greater adoption of linux maybe its bad to be snarky at folks for not instantly understand the terminal based documentation conventions of some dudes in the 70s. Maybe an alphabetical* list of all possible options is okay for referencing or searching, but is objectively insane way to learn or understand a problem.
initially when I was learning linux. I had troubles finding the command I needed. I could have first gone and read everything and then come back to try, which I did. But sometimes the man pages, the ubuntu and arch forums weren’t as great of a help as messing up myself.
Could there be a better way to document with slightly more examples: yes. Would it help: tons
But this is just my opinion, and I am just a noob
“No John, you are the neckbeards!”
as a professional sociotechnical problem solver I will join you on this fatal hill
like take the 4 types of documentation in diátaxis
manpages usually fulfill the reference need, and sometimes kind of that of how-to guides if you’re lucky and your localmanhas examplesbut that leaves more than 50% of documentation needs lacking
and discoverability is atrocious – you have to already know that the command (or commands) you need exists and what it’s called
one of the most useful things I learned in a linux sysadmin course was
apropos/man -k, which lets you search installedmanpages by keyword. but hardly anyone else seems to know about it – I only learned of it because a teaching assistant mentioned it off hand! – and even then it only helps if you guess the right keyword for your problemI am vexed by this situation
People don’t know about man -k because of all the man pages they should have read, they forgot the man one.
I think it should be the default if you don’t use parameters. A little usage help and the list of commands (with a “do you want to see the list of commands? (Y/n)” message)
There’s other ways to get info. And man pages are a great way to learn how something is expected to work on your system. And it’s offline, without ads, scams, ai generated false info.
THIS. I feel like linux
manpages are as useful as an Analytical mechanics textbook for someone who just wants to drive. Like yes, sure, it’s amazing we have such a detailed documentation but for God’s sake just introduce basic usages firstssh [admin@]192.168.1.1 ssh: Could not resolve hostname ]192.168.1.1: No address associated with hostnameThat’s how I would interpret that part of the man page had I no familiarity with ssh. It doesn’t seem reasonable to expect the reader to know what those brackets mean.
You get to learn the notation conventions with <> and [] fairly early on. Maybe a very new user would make that mistake. If he doesn’t get it fairly quick, maybe computers aren’t for him.
They’re searchable and there are examples at the bottom of almost every one of them.
You might be thinking of
infopages. Themanpages are just the instructions, feature flags, etc. generally, whileinfo(when available) usually has a more general / layman description of the command with examples.Hrm, I checked the manpage for grep on my Mac an there are a number of examples. I checked it on Linux and there’s one example. I must be spoiled by the BSD’s.
It’s possible. A lot of things merge the info and man pages now if both are installed, that could be the case here. Or Mac just documents it further.
It’s a good thing there are other resources, then. You can read tldr-pages. You can look at various official and unofficial wikis. You can look at Stackoverflow. You can look at Youtube tutorials. You can ask other people. Hell, you can ask a chatbot.
If the average user is unwilling to do that, maybe it’s better that Linux does not see a wider adoption.
is the fact that people can with effort and error figure out how to do something a reason not to make it easier for them to do?
I mean
you can in theory write multi-threaded bug-free C code – just read the docs and the specs and the source of your libs and never ever do something that seems to work but is subtly fatally incorrect
and yet we still have golang and rust and many other options to do things more safely and easily
if someone wants to use Linux but doesn’t want to memorize the Hundred Mandatory Commands and Thousand Flags lest they accidentally
cat > /dev/sda, why shouldn’t there be a system for them?The community abhors change. Especially changes that break conventions, even informal ones. Look at the temper tantrums people are throwing because Wayland does things differently from X.org. Changing output redirection in Bash, or how
ddworks, or any number of long-standing conventions because new users are unwilling to adapt to a new system and might end updding over the root partition would break established workflows, and worse, existing scripts and services.But the solution already exists, it’s called wrapper programs. You don’t have to manually update AUR packages because
yayandparualready do that. You don’t have to figure out howfdiskandmkfswork because Gparted and Partition Manager do it for you.Nevertheless, using a system should always and forever be the user’s responsibility. Otherwise Linux would turn into a locked-down play pen like Apple products.