News for hackers. Stuff that matters.
Re:Ask HN: Why doesn't anyone ever read the docs? by bjourne on Sunday December 15, 2019 @04:04AM (#21795235)
Because the documentation seldom is good and almost never really good. Long and "complete" documentation isn't the same thing as good documentation.

I have a piece of software and a task I want to accomplish. For example, list files ordered by size in ascending order. ls' man page tells me how to do that, but I have to piece the information together because it is arranged option by option. Thus, I'm forced to read more than what I'd like.

Or I can google "ls sort files by size" click on the first link https://alvinalexander.com/photos/linux-ls-command-how-sort-... and voila.

Most people writing docs don't get that people learn by example. Thus the docs they write lacks examples and therefore are not very useful.

Re:Ask HN: Why doesn't anyone ever read the docs? by atmosx on Sunday December 15, 2019 @04:40AM (#21795337)
> I have a piece of software and a task I want to accomplish. For example, list files ordered by size in ascending order. ls' man page tells me how to do that, but I have to piece the information together because it is arranged option by option. Thus, I'm forced to read more than what I'd like.

If you don't take time to read the entire manpage or at least skim through to find the optimal solution, then you're not experienced enough IMO. I understand the rush to come up with a quick win and amaze everyone, but the first quality I notice on senior engineers is that they were really slow in delivering solutions. The ROI would come up later when drawbacks were documented, the solution was well explained and most of the times elegant, hence no one would need to touch that part of system anytime soon and if someone did had to do so, he'd have a head-start.

Re:Ask HN: Why doesn't anyone ever read the docs? by bjourne on Sunday December 15, 2019 @06:02AM (#21795606)
I think you are projecting. "I'm a good developer and I read man pages so someone who doesn't read man pages must not be a good developer." Maybe YOU are the unexperienced one because YOU don't realize that reading man pages is a waste of time? :P
Re:Ask HN: Why doesn't anyone ever read the docs? by atmosx on Sunday December 15, 2019 @07:04AM (#21795829)
Sure! After all this is the internet, everyone is entitled to an opinion.
Re:Ask HN: Why doesn't anyone ever read the docs? by non-entity on Sunday December 15, 2019 @11:35AM (#21797027)
Pretty much this. I do normally read the docs of whatever I'm working with first, but often they contain some ambiguous or missing inform, or assume I know something else which I may not.

Sometimes its not even the docs that suck, but the site hosting the docs. Microsoft used to be ready bad about this (they're a good but better now) and I swear it used to be impossible to find what I wanted on MSDN without a search engine. I recently also tried to build a certain gcc frontend, and the site had the strangest navigation. Top level links to each documentation section, but then you had to click two small forward and back buttons to continue reading the docs for that section. Ot took me a few minutes to figure that one out.