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.

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.

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.

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 [email protected]

ssh -i ~/.ssh/id_rsa [email protected]

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.

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/ and 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.

indeed. I've always thought this, would be nice to see examples that might cover my need. Then read what the switches/options do.

So you're just going to run some command without knowing what it does, just because it looks right?

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 /^[^ ]

      > ssh [-46AaCfGgKkMNnqsTtVvXxYy] [-B bind_interface] [-b bind_address] [-c cipher_spec] ...

That's exactly the kind of "SYNOPSIS" would make me want to stomp on puppies when looking at a man page because I forgot some basic usage.

But actually, thanks for the key-combo tip on jumping straight to examples.

I find many manpages to be pretty obtuse. They could do a lot to help those of us who need a bit more hand holding.

I like cheat.sh. You can curl it directly from your terminal and it offers the quick examples I often need to get back to work.

Here is their ssh page: http://cheat.sh/ssh

Also I am a huge fan of Matlab’s Documentation, at least up to the more recent versions that became less usable. They give a clear description of the function, list syntax options, give several examples and provide a see also section with similar or related functions (greatly helping discoverability). They usually include academic references at the end.

https://uk.mathworks.com/help/matlab/ref/atand.html?s_tid=do...

Whereas it works great for me so that when I can’t remember the precise syntax I can just glance at the top of the man page; if I want anspecific option I can search for it.

Info format files are intended to be more comprehensive and tutorial but they never really made the jump to Unix.

Sorry, in my Ubuntu 18.04 "man ssh" produces output that does not have either EXAMPLES or USAGE. /^E takes me to ENVIRONMENT instrad of EXAMPLES.

Yes but as I mentioned in my comment for ssh there are several sections that each explain a different use case which you can jump to via /^[^ ]

Sorry, I am confused. In your comment you said that in case of ssh there are several EXAMPLES or USAGES sections. Well, in my case I find exactly zero instances regardless what kind of key combo from your comment I use.

If you instead meant that e.g. TCP FORWARDING or X11 FORWARDING are such sections that explain use cases, well, in that case I still fail to find a section that would describe simple use case of just connecting to a host.

> My usage of manpages would increase by orders of magnitude if I knew there were examples of actual working commands in the first page.

Try adding ManKier as a custom search provider for Firefox or Chrome, it is online man pages beginning with TL;DR examples at the top of each web page, followed by the traditional man page entry below. Here is a fuller explanation with links to instructions for adding it to your browser: https://www.mankier.com/about

I use it almost exclusively now, and only refer to my distro's man page in a terminal if I need to check on something that isn't standardised (such as sed -i.bak or something like that).

Custom browser search is pretty handy, try adding a dictionary and map provider too, or 'caniuse' if you do front-end work.

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

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

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

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.

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.

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.

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.

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