Comment by kccqzy
8 years ago
The main thing about man pages is that it is a "manual": reference material for people who already know the basics.
If you are just getting started, don't read the man pages, but read one of the many "Getting Started" or "Quick Guide" or "Beginning XXX" books. Those will generally be tailored to beginners, including features such as discussions of unifying themes between different commands, historical references and more beginner-friendly organization. Beginners don't need to know all the details at first (which are what the man pages provide), but just the big picture.
Sure, but what usually happens is you sit down at a Unix command line for the first time and have no idea what to do. You ask someone (after seeing that `help` does nothing useful), and they tell you "use 'man' instead of 'help'". And you have no idea why, but you try it and it kind of helps and is better than nothing. You don't have any idea you should `read one of the many "Getting Started" or "Quick Guide" or "Beginning XXX" books.` (Likewise, you wouldn't know at first to install something like this, either.)
I think this is how it used to be, but now people just Google their problems, and typically they get Stack Overflow as a result.
Earlier this year, they announced that they have helped over one million developers to exit vim, for example. https://stackoverflow.blog/2017/05/23/stack-overflow-helping...
In my experience, the top-rated SO answer is typically better than the man page, because it answers the specific question I have, rather than listing all of the options in alphabetical order, forcing me to search the page itself for the information I really wanted.
... or Wikipedia.
Interestingly, Stack Exchange answers are sometimes constructed by people using search engines to find phrase matches, sometimes with ridiculous results. (-:
* https://photo.stackexchange.com/questions/94238/who-or-what-...
That Stack Overflow web log entry is poorly researched, by the way. As I can attest from my own WWW site's statistics, there are reasons that a WWW site can have Ukraine at the top that have nothing to do with real people viewing relevant WWW pages, so conclusions such as
> It looks like developers in Ukraine, Turkey and Indonesia are getting stuck in Vim quite a bit:
are complete rubbish. One has to account for WWW browsers that pre-load pages, and WWW sites that feed stuff scraped from the likes of Wikipedia, Stack Exchange, my WWW site, and lots of others to WWW spiders: something that seems, from my statistics for this month so far, to be very popular for banking and pharmaceutical scam WWW sites in the Ukraine and the Russian Federation.
Here is how to exit emacs, by the way:
* http://jdebp.eu./Humour/exiting-emacs.html
1 reply →
I think I remember reading that a goal of StackOverflow was to essentially build comprehensive documentation of software in a question-answer format. That’s a neat idea. Most mature software has decent documentation in the form of a textbook or a technical manual, but it’s great to have everything documented in the form of “here’s an answer to every question you might have about this software.”
What I like about this though is it's easy to forget the basic options of a command you haven't used in several months. Having the most common use cases at the top of the man page would save a lot of time than digging through some textbook.
a "manual" is not inherently restricted to being a reference. there's no reason a manpage shouldn't include a quick-start guide as well.
Yeah. It looks like some people argue against each other for no reason. I am pretty sure in many fields of work a manual actually explains how to do so me thing. The infamous IKEA manual is an how-to, the last car manuals all had how-tos include: how to change radio station, how to change oil,...
Is their ever a moment, that some picks up a manual and doesn't want to know how to do something?
Usually it’s just me trying to do some task and not caring to ever “learn the command” with any depth (because I don’t use it enough for that to be worthwhile). That’s why examples are great. I can probably usually just scan the examples and quickly recognize the one that does the thing I want to do.
Of course, sometimes this attitude of mine is a problem. The most obvious example for me is git, which I use nearly every day, but still have an embarrassingly shallow understanding of. Any time something “goes wrong” I’m googling for a magic command to fix it, or resorting to crude measures like copying the whole repo directory and resetting hard.
>The most obvious example for me is git, which I use nearly every day, but still have an embarrassingly shallow understanding of. Any time something “goes wrong” I’m googling for a magic command to fix it,
This is basically the reason I use Mercurial. It actually makes sense without getting a bloody degree in "how to use your DVCS", and the help is quite nice, and not a godawful clusterfuck like some popular DCVSes that were developed by developers of major FOSS kernels circa 2005.