Ask HN: Why doesn't anyone ever read the docs? • Hacker News Board

Re: Ask HN: Why doesn't anyone ever read the docs?

#11

Post by atmosx » Sun, Dec 15, 2019, 12:04 PM UTC

bjourne wrote: post #10

atmosx wrote: post #9

Earlier quoted context omitted.

> 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 exp…

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

Sure! After all this is the internet, everyone is entitled to an opinion.

Re: Ask HN: Why doesn't anyone ever read the docs?

#12

Post by markus_zhang » Sun, Dec 15, 2019, 1:46 PM UTC

I think they serve different purposes. For example Python pandas has excellent documentation, and usually that's enough if you need to know how to use a function.

However, for many programmers the difficulty is to break down real problems into functions, and docs however good they are, won't help much.

Re: Ask HN: Why doesn't anyone ever read the docs?

#13

Post by non-entity » Sun, Dec 15, 2019, 4:35 PM UTC

bjourne wrote: post #8

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 mo…

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.