8 ms·

Notice how the answer starts with "From the <documentation>" ... It's unfortunate that people no longer dive into original system/program documentation, but go

by zytek 12y ago

Notice how the answer starts with "From the <documentation>" ... It's unfortunate that people no longer dive into original system/program documentation, but google/ask for quick answer. When I started my unix/linux journey some ~14 years ago I always found something more when reading docs and thought of guru's as "these guys that read more docs than I did". Similarly you may noticed how you can no longer write code comfortably when being offline, because you cannot google "how to make dict() return default value for non existing key" etc. I am now in the process of killing this bad habit of googling through my "coding" and sysadmin tasks, rather than reading docs and examples available on my system. PS. sorry for my english

nwh 12y ago
Don't be!
ketralnis 12y ago
I'm perfectly fine with needing to look up half of the functions I call or syntax for something I don't do often. As long as documentation is good, I just consider it outsourcing the bits of my brain that I'm bad at (memorisation) so that I can spend my thinking time solving my actual problem. But what really bothers me is the number of people that ask someone else before consulting the documentation. IRC, Stack Overflow, and mailing lists seem to be full of questions that are exact copies of #1 in the FAQ or easily answered with a quick trip to `man`. Or even quickly searching the place that they asked for the other twenty people that have asked this question today. Just look at the front page of Stack Overflow. Any any given day it seems to have half "here's a stack trace that I haven't bothered to read. fixitfixitfixit" and half questions that might as well be the exact title of the man page that they should read.
AceJohnny2 12y ago
> It's unfortunate that people no longer dive into original system/program documentation, but google/ask for quick answer. I've been thinking about this myself. I think there's good reason: Google (or a bunch of experts on hand) will often provide a better, more concise answer to your specific question than having to search and grok the manpages. As extreme examples, I regularly ragequit the Bash manpage after trying to find the meaning of some keywords, and the Sudoers manpage is notorious with presenting the syntax as EBNF without examples! (a pity GNU Info never fixed their interface, the idea's good)
- lambda 12y ago
  For bash keywords, don't look in the man page, try "help <word>". The Bash man page does not contain a complete description of Bash, only a brief summary. "man <builtin>" provides a generic builtins page usually, since the builtins can vary between shells so one man page can't cover all of the different shell behaviors. However, bash has a "help" command which will give you the bash-specific description of a given builtin. Other than that, I usually find the HTML Bash documentation easier to read and navigate than the info, so I just use that instead. And yes, the sudoers man page is pure evil.
  - JetSpiegel 12y ago
    After ragequitting the builtins manpage, created a hack/bash script that checks the type of the command and alternates between manpage, help <cmd> or alias.
- contingencies 12y ago
  What was that quote again? Let me google that for you. Those who would give up essential liberty to purchase a little temporary safety deserve neither liberty nor safety. Benjamin Franklin, Historical Review of Pennsylvania, 1759 Trading long term independence for temporary efficiency never looked so good!
- vacri 12y ago
  My pet hate is man pages for things with lots of options, where the options are neither semantically nor alphabetically grouped (eg rsync list-o-options). Second to that is the 'example' where every single option possible is given, while at the same time not having a typical usage example. When there's 50 potential flags with arguments, I lose track of how to structure the command - it's somewhere in all those square brackets... somewhere...
lambda 12y ago
Sometimes, Googling can be a lot quicker than finding the answer in the documentation. Sometimes, the documentation does not exist. Sometimes, the documentation is wrong and Googling finds a discussion that corrects it. Sometimes, you don't actually know what documentation to start with because a system is so new to you that you don't know what you need to know. When I answer questions on Stack Overflow/Stack Exchange, if the answer is in the documentation, I always try to link to it, while also providing a brief and clear explanation in the answer in case the documentation might be hard to interpret. I hope that helps with some of those people who don't know where to start in the documentation, or may have had trouble understanding it. For example, in this case, the documentation is hidden away in the kernel source tree. If you don't have a kernel source checkout, you may not have this documentation available on your system at all; and even if you did, you may not think to look there. This should be documented in a man page somewhere, but there's a long list of things that should be documented in man pages which are not: https://www.kernel.org/doc/man-pages/missing_pages.html https://www.kernel.org/doc/man-pages/missing_pages.html It is a good idea to learn how to find information in common documentation sources that are available on your system. One problem is that Google frequently winds up being a better answer than local documentation because it offers a single interface to find all kinds of documentation, rather than having to learn dozens of different interfaces and places to look, only some of which are easily searchable. Off the top of my head, here are a few places that I've needed to look for documentation recently: man pages, /usr/share/doc, kernel source, perldoc, pydoc, rdoc, info, Gnome Devel Docs, and so on. Gurus haven't always read more docs than you have. Sometimes they had to read the source. Sometimes they've just learned through trial and error, and reasoning about how stuff probably works. Sometimes they learned by word of mouth from someone else with experience. Reading the docs can definitely help; it can let you know about functionality that you've never thought to look for. But it's not the only tool for learning about a system, and how effective it is depends heavily on how thorough and good the documentation for the system is.
deleted 12y ago
[deleted]
pwg 12y ago
> It's unfortunate that people no longer dive into original system/program documentation, but google/ask for quick answer. >Similarly you may noticed how you can no longer write code comfortably when being offline, because you cannot google "how to make dict() return default value for non existing key" etc. A large reason for this is the change that has occurred over time from old-school Unix type tools to newer tools. In many cases, the newer languages simply have no documentation available locally. I.e., in my Slackware system, I have (): 1,596 man pages for glibc functions 896 man pages for Perl 155 man pages for Tcl functions 88 man pages for Tk functions 1 man page for Python One can "code disconnected" reasonably well in C/C++, Perl, or Tcl/Tk because the tools also installed documentation for all the functions contained therein. But, with Python, without a separate set of docs, or internet access, one is lost if one needs to "look something up". Plus, jumping out of one's editor (or switching to another xterm) to run "man 3 printf" to look-up a particular obscure percent escape is loads faster than googling for the same. There is an advantage to having full local documentation installed. But it seems that the advantage has been lost on some tools. () count obtained by grep and wc -l on Slackware's packages files
- vacri 12y ago
  In Debian derivatives, there's the installable package 'python-doc', though I don't know it's quality.
- yew 12y ago
  Python does provide internal documentation tools via docstrings and the processing/viewing system for them (and the documentation for the standard library is generally good). You might also have a local copy of the online documentation installed (the package is usually named something like python-doc). The lack of comprehensive offline documentation that seems to be becoming more and more common even for large projects is rather troubling, though.
- bbanyc 12y ago
  From the python man page: "Documentation for installed Python modules and packages can be viewed by running the pydoc program." pydoc is part of the standard Python installation (though it might be broken out into a separate package on some Linux distros) and equivalent to the man pages for Perl and Tcl. Java, on the other hand, typically only has the HTML javadocs. And once you get outside libc, documentation for C/C++ libraries is all over the place in formatting and accessibility with standard tools.
logn 12y ago
For programming issues, I'll often google just to get to the reference pages because it's not worth CTRL-F-ing through a local site to get docs on the class/function/etc you need (or installing your own search engine). And there are times when Stack Overflow is a lifesaver for weird bugs, poorly documented APIs, etc. It's much better than the alternative of, say, reading the release notes for the last 20 versions to see why code breaks on the latest. Also, I think googling for CSS issues will be a never-ending thing, because the technology is so weird sometimes, and inconsistent (is it white-space:nowrap ... or whitespace:no-wrap ... idk, grammatically they each need a dash). For some reason CSS's approach of just having hundreds of attributes the can be individually set is not memorizable to me, whereas Java SE mostly is. And there's always that rare linux command that's kind of a once-a-year thing, like setting the trackpad timeout while typing (syndaemon -i .1 -d ... I don't care if I never remember that program... probably how some people feel about programming questions).

by zytek 12y ago

nwh 12y ago

Don't be!

ketralnis 12y ago

I'm perfectly fine with needing to look up half of the functions I call or syntax for something I don't do often. As long as documentation is good, I just consider it outsourcing the bits of my brain that I'm bad at (memorisation) so that I can spend my thinking time solving my actual problem. But what really bothers me is the number of people that ask someone else before consulting the documentation. IRC, Stack Overflow, and mailing lists seem to be full of questions that are exact copies of #1 in the FAQ or easily answered with a quick trip to `man`. Or even quickly searching the place that they asked for the other twenty people that have asked this question today. Just look at the front page of Stack Overflow. Any any given day it seems to have half "here's a stack trace that I haven't bothered to read. fixitfixitfixit" and half questions that might as well be the exact title of the man page that they should read.

AceJohnny2 12y ago

> It's unfortunate that people no longer dive into original system/program documentation, but google/ask for quick answer. I've been thinking about this myself. I think there's good reason: Google (or a bunch of experts on hand) will often provide a better, more concise answer to your specific question than having to search and grok the manpages. As extreme examples, I regularly ragequit the Bash manpage after trying to find the meaning of some keywords, and the Sudoers manpage is notorious with presenting the syntax as EBNF without examples! (a pity GNU Info never fixed their interface, the idea's good)

lambda 12y ago
For bash keywords, don't look in the man page, try "help <word>". The Bash man page does not contain a complete description of Bash, only a brief summary. "man <builtin>" provides a generic builtins page usually, since the builtins can vary between shells so one man page can't cover all of the different shell behaviors. However, bash has a "help" command which will give you the bash-specific description of a given builtin. Other than that, I usually find the HTML Bash documentation easier to read and navigate than the info, so I just use that instead. And yes, the sudoers man page is pure evil.
- JetSpiegel 12y ago
  After ragequitting the builtins manpage, created a hack/bash script that checks the type of the command and alternates between manpage, help <cmd> or alias.
contingencies 12y ago
What was that quote again? Let me google that for you. Those who would give up essential liberty to purchase a little temporary safety deserve neither liberty nor safety. Benjamin Franklin, Historical Review of Pennsylvania, 1759 Trading long term independence for temporary efficiency never looked so good!
vacri 12y ago
My pet hate is man pages for things with lots of options, where the options are neither semantically nor alphabetically grouped (eg rsync list-o-options). Second to that is the 'example' where every single option possible is given, while at the same time not having a typical usage example. When there's 50 potential flags with arguments, I lose track of how to structure the command - it's somewhere in all those square brackets... somewhere...

lambda 12y ago

Sometimes, Googling can be a lot quicker than finding the answer in the documentation. Sometimes, the documentation does not exist. Sometimes, the documentation is wrong and Googling finds a discussion that corrects it. Sometimes, you don't actually know what documentation to start with because a system is so new to you that you don't know what you need to know. When I answer questions on Stack Overflow/Stack Exchange, if the answer is in the documentation, I always try to link to it, while also providing a brief and clear explanation in the answer in case the documentation might be hard to interpret. I hope that helps with some of those people who don't know where to start in the documentation, or may have had trouble understanding it. For example, in this case, the documentation is hidden away in the kernel source tree. If you don't have a kernel source checkout, you may not have this documentation available on your system at all; and even if you did, you may not think to look there. This should be documented in a man page somewhere, but there's a long list of things that should be documented in man pages which are not: https://www.kernel.org/doc/man-pages/missing_pages.html https://www.kernel.org/doc/man-pages/missing_pages.html It is a good idea to learn how to find information in common documentation sources that are available on your system. One problem is that Google frequently winds up being a better answer than local documentation because it offers a single interface to find all kinds of documentation, rather than having to learn dozens of different interfaces and places to look, only some of which are easily searchable. Off the top of my head, here are a few places that I've needed to look for documentation recently: man pages, /usr/share/doc, kernel source, perldoc, pydoc, rdoc, info, Gnome Devel Docs, and so on. Gurus haven't always read more docs than you have. Sometimes they had to read the source. Sometimes they've just learned through trial and error, and reasoning about how stuff probably works. Sometimes they learned by word of mouth from someone else with experience. Reading the docs can definitely help; it can let you know about functionality that you've never thought to look for. But it's not the only tool for learning about a system, and how effective it is depends heavily on how thorough and good the documentation for the system is.

deleted 12y ago

[deleted]

pwg 12y ago

> It's unfortunate that people no longer dive into original system/program documentation, but google/ask for quick answer. >Similarly you may noticed how you can no longer write code comfortably when being offline, because you cannot google "how to make dict() return default value for non existing key" etc. A large reason for this is the change that has occurred over time from old-school Unix type tools to newer tools. In many cases, the newer languages simply have no documentation available locally. I.e., in my Slackware system, I have (): 1,596 man pages for glibc functions 896 man pages for Perl 155 man pages for Tcl functions 88 man pages for Tk functions 1 man page for Python One can "code disconnected" reasonably well in C/C++, Perl, or Tcl/Tk because the tools also installed documentation for all the functions contained therein. But, with Python, without a separate set of docs, or internet access, one is lost if one needs to "look something up". Plus, jumping out of one's editor (or switching to another xterm) to run "man 3 printf" to look-up a particular obscure percent escape is loads faster than googling for the same. There is an advantage to having full local documentation installed. But it seems that the advantage has been lost on some tools. () count obtained by grep and wc -l on Slackware's packages files

vacri 12y ago
In Debian derivatives, there's the installable package 'python-doc', though I don't know it's quality.
yew 12y ago
Python does provide internal documentation tools via docstrings and the processing/viewing system for them (and the documentation for the standard library is generally good). You might also have a local copy of the online documentation installed (the package is usually named something like python-doc). The lack of comprehensive offline documentation that seems to be becoming more and more common even for large projects is rather troubling, though.
bbanyc 12y ago
From the python man page: "Documentation for installed Python modules and packages can be viewed by running the pydoc program." pydoc is part of the standard Python installation (though it might be broken out into a separate package on some Linux distros) and equivalent to the man pages for Perl and Tcl. Java, on the other hand, typically only has the HTML javadocs. And once you get outside libc, documentation for C/C++ libraries is all over the place in formatting and accessibility with standard tools.

logn 12y ago

For programming issues, I'll often google just to get to the reference pages because it's not worth CTRL-F-ing through a local site to get docs on the class/function/etc you need (or installing your own search engine). And there are times when Stack Overflow is a lifesaver for weird bugs, poorly documented APIs, etc. It's much better than the alternative of, say, reading the release notes for the last 20 versions to see why code breaks on the latest. Also, I think googling for CSS issues will be a never-ending thing, because the technology is so weird sometimes, and inconsistent (is it white-space:nowrap ... or whitespace:no-wrap ... idk, grammatically they each need a dash). For some reason CSS's approach of just having hundreds of attributes the can be individually set is not memorizable to me, whereas Java SE mostly is. And there's always that rare linux command that's kind of a once-a-year thing, like setting the trackpad timeout while typing (syndaemon -i .1 -d ... I don't care if I never remember that program... probably how some people feel about programming questions).