3 ms·

> Man pages are notoriously a colossal waste of time. In general they are poorly thought out, they are incomplete, they were written with complete disregard for

by pxc 2y ago

> Man pages are notoriously a colossal waste of time. In general they are poorly thought out, they are incomplete, they were written with complete disregard for user experience, and more often than not they are way out of date. Uh, what? What man pages are you reading? I read manpages all the time, and I've never run into an issue where one contained info that was untrue because outdated. The only manpages I've ever read that I'd characterize as incomplete are Apple's.¹ > Why do you think sites like Stack overflow is so popular? Because all those "incurious" people in tech feels the need to ask questions and dig through answers on how to solve problems? One of the reasons Stack Overflow is so popular is that people who can't/won't read docs can use it to have answers spoonfed to them, often by people who only differ from them in being more willing/able to read the docs. Isn't that extremely obvious? > unreadable documents Reading isn't a singular skill— each genre requires its own skills, and you gradually pick those up by reading in that genre. Reading novels doesn't much prepare you to read math textbooks, but that doesn't make all math textbooks 'unreadable'. The same things goes for skimming. Skimming a text is likewise a (set of) genre-specific skill(s), built up through practice. Frankly, moving from your terminal to your web browser to look up how to use a CLI tool is only consistently faster than working with the docs native to that CLI environment (man pages, info pages, usage messages, --help flags, help subcommands, tldr pages, etc.) if you have don't have very good reading skills in the genres of those native docs. As someone who does not have difficulty skimming or navigating manpages quickly, when someone tells me that digging through StackOverflow seems like less of a waste of time than reading docs and so they never read docs, I have to wonder if the real issue is that a reading skills deficit is caught in a self-reinforcing loop. And indeed, a trip to StackOverflow never ends at StackOverflow for a person with much curiosity. Because even if a curious person finds a solution to their immediate problem, they will wonder things like: - is this solution outmoded by some other fix? - how is the feature/option/change used in this solution actually supposed to work? - are there any alternatives I should know about? - if I wanted to do things slightly differently, could I still use the method/feature/option referenced in this solution? does it have any parameters that are easy to swap or tweak? - is this scenario what the feature/method/option in the solution is actually intended for? should I care? ... and the quickest way to answer questions like that is usually a glance at a manual. ----- 1: In some cases with GNU stuff the literal `man` pages are abridged versions of the `info` pages. But even then, the `man` pages direct you to `info` pages. It's not like they leave you having.

chipdart 2y ago
> Uh, what? What man pages are you reading? Every single man page out there leads to a user experience that is at best subpar. > One of the reasons Stack Overflow is so popular is that people who can't/won't read docs can use it to have answers spoonfed to them (...) Pause and look at what you're saying. Your only criticism of SO is how it improves the task of providing meaningful information to users. The way you opt to spin improvements to user experience as "spoonfed" speaks volumes of your inability to understand the problem and the value you place on gratuitous ladder-pulling. You even contradict your remarks on man pages. > Reading isn't a singular skill— each genre requires its own skills (...) No. Writing is a skill. Producing content that the target audience is able to consume and brings value is a skill. The moment you, as a end-user, feel the need to hunker down and decipher arcane texts is the moment you should realize the documentation is bad. Again, Stack overflow is widely used as ad-hoc crowd-sourced documentation for a reason. Some project maintainers even go as far as to make it their own channel to provide technical support. Why so? Do you honestly believe its because the whole world is not smart enough to read man pages? Again, those who do not waste their time on man pages are the smart ones who put their own time to better use.
- sgarland 2y ago
  > Your only criticism of SO is how it improves the task of providing meaningful information to users... the value you place on gratuitous ladder-pulling How is wanting others to learn ladder-pulling? Also, how do you assume people will have this kind of information handed to them when the people who are interested in deeply learning stop doing so, die off, etc.? If you say AI, first of all, best of luck with the hallucinations, but secondly, who is going to work on and train the AI? > No. Writing is a skill. Producing content that the target audience is able to consume and brings value is a skill. The moment you, as an end-user, feel the need to hunker down and decipher arcane texts is the moment you should realize the documentation is bad. I think I see the root disagreement here. You continue to mention "value," as though reading is itself not valuable. Sitting down to read a work of fiction arguably brings no value to anyone (except perhaps the author and publisher), yet millions do it anyway. Similarly, if I find a way to do something, I usually want to know if there are also other ways, and if so, if they're better. There's not much "value" there most of the time, but it brings me happiness, and enhances my knowledge of the subject.

by pxc 2y ago

chipdart 2y ago

> Uh, what? What man pages are you reading? Every single man page out there leads to a user experience that is at best subpar. > One of the reasons Stack Overflow is so popular is that people who can't/won't read docs can use it to have answers spoonfed to them (...) Pause and look at what you're saying. Your only criticism of SO is how it improves the task of providing meaningful information to users. The way you opt to spin improvements to user experience as "spoonfed" speaks volumes of your inability to understand the problem and the value you place on gratuitous ladder-pulling. You even contradict your remarks on man pages. > Reading isn't a singular skill— each genre requires its own skills (...) No. Writing is a skill. Producing content that the target audience is able to consume and brings value is a skill. The moment you, as a end-user, feel the need to hunker down and decipher arcane texts is the moment you should realize the documentation is bad. Again, Stack overflow is widely used as ad-hoc crowd-sourced documentation for a reason. Some project maintainers even go as far as to make it their own channel to provide technical support. Why so? Do you honestly believe its because the whole world is not smart enough to read man pages? Again, those who do not waste their time on man pages are the smart ones who put their own time to better use.

sgarland 2y ago
> Your only criticism of SO is how it improves the task of providing meaningful information to users... the value you place on gratuitous ladder-pulling How is wanting others to learn ladder-pulling? Also, how do you assume people will have this kind of information handed to them when the people who are interested in deeply learning stop doing so, die off, etc.? If you say AI, first of all, best of luck with the hallucinations, but secondly, who is going to work on and train the AI? > No. Writing is a skill. Producing content that the target audience is able to consume and brings value is a skill. The moment you, as an end-user, feel the need to hunker down and decipher arcane texts is the moment you should realize the documentation is bad. I think I see the root disagreement here. You continue to mention "value," as though reading is itself not valuable. Sitting down to read a work of fiction arguably brings no value to anyone (except perhaps the author and publisher), yet millions do it anyway. Similarly, if I find a way to do something, I usually want to know if there are also other ways, and if so, if they're better. There's not much "value" there most of the time, but it brings me happiness, and enhances my knowledge of the subject.