4 ms·

If you liked this article, PLEASE, PLEASE just take 10 minutes to look at the manpages for ssh(1) and ssh_config(5). SSH options are nothing we need to researc

If you liked this article, PLEASE, PLEASE just take 10 minutes to look at the manpages for ssh(1) and ssh_config(5). SSH options are nothing we need to research about, we humans made it and we wrote documentation for it. The manpages are also exhaustive, definitive, and valid for the exact version you have installed. Please, instead of making more 'how to use SSH'-articles popular, read the manpages yourself. Reading the datasheets and documentation of the stuff you work with is an important characteristic of an capable engineer.

bmn__ 8y ago
Do you want to get rid of how-tos? Both references and how-tos are needed. They serve different purposes.
lucideer 8y ago
> Reading the datasheets and documentation of the stuff you work with is an important characteristic of an capable engineer. I completely agree with this statement, but that doesn't nullify the value of "how to use x" articles. Man-pages are great because: - they're (mostly) ubiquitous - they're plaintext, meaning their format is more robust and accessible (e.g. I can read man over SSH without ever encountering issues) and these are great pros, but in certain relevant aspects they're grossly inferior to articles like this: - man-pages must be exhaustive, and thus don't have the luxury of focusing on the most common use-cases up front. These are often relegated to the "Examples" section only, or omitted altogether - screenshots. Even for terminal apps, screenshots are incredibly helpful, and in this particular article they're also used to demonstrate the use of applications your SSH connection will interact with (e.g. browser proxy/network settings) - (related to the above) contextual information that would otherwise be off-topic/inappropriate in a man-page. How-to articles can cover multiple apps that interact with eachother as one topic; i.e. a how-to article can focus on a use case rather than a single app.
evrflx 8y ago
While your point is valid it applies to a single tool. Often the combination of multiple tools and Unix knowledge is what provides a simple solution to common problems. Not everybody has the broad knowledge to come up with these themselves so tutorial articles are a valid and helpful complement to man pages in my point of view.
barrkel 8y ago
Man pages and other documentation are usually reference oriented. That means they are complete, verbose, detail-oriented and structured around functionality and options. When learning, however, we often need goal directed material and examples. For multi-purpose tools - and most tools have more than one application, especially for higher level goals - that means there can be many different introductions for the same tool, depending on the learner's goal. The best tools are compositional. Often it's hard to imagine all the ways a tool can be composed by looking at it in isolation. You need some examples to get the imagination working.
beefield 8y ago
My usage of manpages would increase by orders of magnitude if I knew there were examples of actual working commands in the first page. Most of the time I am not looking for an obscure parameter, but my brain just has failed to take a note of the basic syntax of the command. So why not start ssh manpage with two simple examples, how to connect to a host with username and ssh key: ssh user@example.com ssh -i ~/.ssh/id_rsa user@example.com
- sshagent 8y ago
  indeed. I've always thought this, would be nice to see examples that might cover my need. Then read what the switches/options do.
  - funklebunkle 8y ago
    So you're just going to run some command without knowing what it does, just because it looks right?
- cygned 8y ago
  That is the reason why I like the Golang documentation; it consists of exhaustive comments, (runnable) examples, explanatory code snippets and links to the corresponding source. Works as a reference but also for explorative learning.
- dspillett 8y ago
  There are a few projects out there trying to do this as community driven efforts or by extracting examples automatically from the existing man pages (or a mix of the two). https://tldr.sh/ https://tldr.sh/ and http://bropages.org/ http://bropages.org/ spring to mind, and I know there are others that I'm not immediately remembering ATM, both of which have web interfaces or can be installed as local command-line tools.
- gumby 8y ago
  This is how every man page starts, with a "SYNOPSIS" of invocation. For example the ssh man page starts: ssh [-46AaCfGgKkMNnqsTtVvXxYy] [-B bind_interface] [-b bind_address] [-c cipher_spec] ... If there are several incompatible ways to invoke an operation several cases are given, e.g. netstat [-AaLlnW] [-f address_family | -p protocol] netstat [-gilns] [-v] [-f address_family] [-I interface] ... Typically there are examples in the EXAMPLES or USAGE section which you can jump straight to via /^U or /^E In the case of ssh there are several such sections so just jump to them via /^[^ ]
ozim 8y ago
I don't really want to read dictionary cover to cover to learn english.
ReptileMan 8y ago
Sometimes all you need is a cheat sheet. Deep understanding of the tools is valuable, but not always have good ROI if it is not in your core task. Especially for standard/common/trivial tasks. It can bite your ass of course, but it is rare - and if you do something more exotic - take the time learning to minimize the chance.
deleted 8y ago
[deleted]
LinuxBender 8y ago
Man pages can be great and people should always read them first. That said, I find that man pages often lack a wide sample of configuration examples, implementation examples and useful tips. This is where blogs and vlogs fill in the gaps. Man pages often leave many things to interpretation that varies wildly from person to person. Man pages sometimes also leave out best practices and caveats.
skywhopper 8y ago
I think you are dead wrong with this plea. Explanation and reference are two very different things, and both can't exist effectively in the same document. The man pages are great once you have the concepts down. But there's a huge gap out there for introductory explanations of the concepts behind the tools that the man pages (rightfully) assume you already have mastered. This article is a great example of the type of thing we need a lot more of. If you know you want a SOCKS proxy and just need to know the correct option name, the man pages are great. If you have no idea what a SOCKS proxy is, why you might want it, or even that ssh can solve this problem for you, then there's no chance you'd even think to look at the man pages for ssh and ssh_config, and if you did, you still wouldn't really know what the bits about SOCKS proxy meant for you and your problems. It's not like this article's existence will prevent people from reading the man pages. On the contrary, this article serves an entirely different purpose. I can read it on my phone, learn about something new, and then when I'm back at my workstation, I can look up the new concept in the man pages to figure out how I can integrate it into my own workflow. I'm struggling with understanding the motivation behind your post here. Please reconsider the value of this sort of article in combination with the value of man pages.
- jolmg 8y ago
  I find myself agreeing with both of you. You're right that having articles like this makes the tools more accessible and understandable to those that use both resources. However, it seems that most people don't use both resources. Many rely only on these sorts of articles and don't RTFM. There is a lot of power in many *nix tools that people could benefit from but don't realize it because they don't even skim over the manual. It wasn't that long ago that it was common for people read the manuals of the things they used to get the best bang for their buck, so to speak. Now, the world is filled with quick-starts and use-specific guides, because people don't have the time to research all the things they use. It's this aversion to a little studying of the tools of our trade that I think blueflow and myself are against.
Raphmedia 8y ago
Cookbooks are also important. Sure, if you learn every single ingredients you might be a good cook... but if you read recipes, you will be able to cook well no matter what.
ecp9 8y ago
manpages are such an inconsistent and often wildly disappointing experience that I advise everyone to give up on them and go with <any top internet tutorial> instead. There are like a half dozen really good manpages I can think of, some others might as well be written in Mandarin

bmn__ 8y ago

Do you want to get rid of how-tos? Both references and how-tos are needed. They serve different purposes.

lucideer 8y ago

> Reading the datasheets and documentation of the stuff you work with is an important characteristic of an capable engineer. I completely agree with this statement, but that doesn't nullify the value of "how to use x" articles. Man-pages are great because: - they're (mostly) ubiquitous - they're plaintext, meaning their format is more robust and accessible (e.g. I can read man over SSH without ever encountering issues) and these are great pros, but in certain relevant aspects they're grossly inferior to articles like this: - man-pages must be exhaustive, and thus don't have the luxury of focusing on the most common use-cases up front. These are often relegated to the "Examples" section only, or omitted altogether - screenshots. Even for terminal apps, screenshots are incredibly helpful, and in this particular article they're also used to demonstrate the use of applications your SSH connection will interact with (e.g. browser proxy/network settings) - (related to the above) contextual information that would otherwise be off-topic/inappropriate in a man-page. How-to articles can cover multiple apps that interact with eachother as one topic; i.e. a how-to article can focus on a use case rather than a single app.

evrflx 8y ago

While your point is valid it applies to a single tool. Often the combination of multiple tools and Unix knowledge is what provides a simple solution to common problems. Not everybody has the broad knowledge to come up with these themselves so tutorial articles are a valid and helpful complement to man pages in my point of view.

barrkel 8y ago

Man pages and other documentation are usually reference oriented. That means they are complete, verbose, detail-oriented and structured around functionality and options. When learning, however, we often need goal directed material and examples. For multi-purpose tools - and most tools have more than one application, especially for higher level goals - that means there can be many different introductions for the same tool, depending on the learner's goal. The best tools are compositional. Often it's hard to imagine all the ways a tool can be composed by looking at it in isolation. You need some examples to get the imagination working.

beefield 8y ago

My usage of manpages would increase by orders of magnitude if I knew there were examples of actual working commands in the first page. Most of the time I am not looking for an obscure parameter, but my brain just has failed to take a note of the basic syntax of the command. So why not start ssh manpage with two simple examples, how to connect to a host with username and ssh key: ssh user@example.com ssh -i ~/.ssh/id_rsa user@example.com

sshagent 8y ago
indeed. I've always thought this, would be nice to see examples that might cover my need. Then read what the switches/options do.
- funklebunkle 8y ago
  So you're just going to run some command without knowing what it does, just because it looks right?
cygned 8y ago
That is the reason why I like the Golang documentation; it consists of exhaustive comments, (runnable) examples, explanatory code snippets and links to the corresponding source. Works as a reference but also for explorative learning.
dspillett 8y ago
There are a few projects out there trying to do this as community driven efforts or by extracting examples automatically from the existing man pages (or a mix of the two). https://tldr.sh/ https://tldr.sh/ and http://bropages.org/ http://bropages.org/ spring to mind, and I know there are others that I'm not immediately remembering ATM, both of which have web interfaces or can be installed as local command-line tools.
gumby 8y ago
This is how every man page starts, with a "SYNOPSIS" of invocation. For example the ssh man page starts: ssh [-46AaCfGgKkMNnqsTtVvXxYy] [-B bind_interface] [-b bind_address] [-c cipher_spec] ... If there are several incompatible ways to invoke an operation several cases are given, e.g. netstat [-AaLlnW] [-f address_family | -p protocol] netstat [-gilns] [-v] [-f address_family] [-I interface] ... Typically there are examples in the EXAMPLES or USAGE section which you can jump straight to via /^U or /^E In the case of ssh there are several such sections so just jump to them via /^[^ ]

ozim 8y ago

I don't really want to read dictionary cover to cover to learn english.

ReptileMan 8y ago

Sometimes all you need is a cheat sheet. Deep understanding of the tools is valuable, but not always have good ROI if it is not in your core task. Especially for standard/common/trivial tasks. It can bite your ass of course, but it is rare - and if you do something more exotic - take the time learning to minimize the chance.

deleted 8y ago

[deleted]

LinuxBender 8y ago

Man pages can be great and people should always read them first. That said, I find that man pages often lack a wide sample of configuration examples, implementation examples and useful tips. This is where blogs and vlogs fill in the gaps. Man pages often leave many things to interpretation that varies wildly from person to person. Man pages sometimes also leave out best practices and caveats.

skywhopper 8y ago

I think you are dead wrong with this plea. Explanation and reference are two very different things, and both can't exist effectively in the same document. The man pages are great once you have the concepts down. But there's a huge gap out there for introductory explanations of the concepts behind the tools that the man pages (rightfully) assume you already have mastered. This article is a great example of the type of thing we need a lot more of. If you know you want a SOCKS proxy and just need to know the correct option name, the man pages are great. If you have no idea what a SOCKS proxy is, why you might want it, or even that ssh can solve this problem for you, then there's no chance you'd even think to look at the man pages for ssh and ssh_config, and if you did, you still wouldn't really know what the bits about SOCKS proxy meant for you and your problems. It's not like this article's existence will prevent people from reading the man pages. On the contrary, this article serves an entirely different purpose. I can read it on my phone, learn about something new, and then when I'm back at my workstation, I can look up the new concept in the man pages to figure out how I can integrate it into my own workflow. I'm struggling with understanding the motivation behind your post here. Please reconsider the value of this sort of article in combination with the value of man pages.

jolmg 8y ago
I find myself agreeing with both of you. You're right that having articles like this makes the tools more accessible and understandable to those that use both resources. However, it seems that most people don't use both resources. Many rely only on these sorts of articles and don't RTFM. There is a lot of power in many *nix tools that people could benefit from but don't realize it because they don't even skim over the manual. It wasn't that long ago that it was common for people read the manuals of the things they used to get the best bang for their buck, so to speak. Now, the world is filled with quick-starts and use-specific guides, because people don't have the time to research all the things they use. It's this aversion to a little studying of the tools of our trade that I think blueflow and myself are against.

Raphmedia 8y ago

Cookbooks are also important. Sure, if you learn every single ingredients you might be a good cook... but if you read recipes, you will be able to cook well no matter what.

ecp9 8y ago

manpages are such an inconsistent and often wildly disappointing experience that I advise everyone to give up on them and go with <any top internet tutorial> instead. There are like a half dozen really good manpages I can think of, some others might as well be written in Mandarin