Ask HN: Why doesn't anyone ever read the docs? | Hacker News Reader

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

13 pointssnejad12311 comments

This is one of the strangest behaviors i've seen in programming. I understand some docs are incomplete or incoherent but most of them are really good, especially the ones coming out of an enterprise setting (React, GraphQL, Apache, etc.).

Most engineers I know rush to youtube or medium or some other outsourced interpretation of the docs that is far more scattered in info. I was wondering what made you (if you're one of the types that prefers medium/YT over the documentation) prefer these off-hand interpretations of a program rather than the one who created it ?

View on HN

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.

> 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.

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.

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.

Docs often describe what the one documenting has in mind while designing, explaining already known facts to herself/himself from the point of view past understanding the domain.

Users start fresh. If users had spent as much time as the one documenting they would probably love the documentation, but since they are new, the viewpoint differs.

Truly good and intelligent documentation tries to capture the mindset of the assumed reader.

1. The design of documentation is usually atrocious (PHPs language docs make me throw up in my mouth a little every time I see them)

2. Documentation is written by super smart people designed the software... they tend to have a tough time relating to normal developers and especially beginners

3. Docs never provide enough examples. Stack overflow literally exists for this reason

4. Documentation is an after thought for most pieces of software (laravel is a notable example to the contrary - the docs are part of the software design for laravel), and not a forethought.

5. People just don't read period

6. Documentation usually has contrived examples, where other sources often have literally the think that you were trying to do (Users, Posts, Payments, Tags, etc)

Short list... but hopefully helpful

I recently worked with a professor leading grad students in a software development project, he told me they seemed somehow cognitively incapable of absorbing information from standard docs and man pages. When they came to him with questions, he'd show them the answers plainly available in the docs. But when it came to finding answers on their own, they were totally dependent on web forums and such online resources.

A matter of generational cultural conditioning I guess.

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.

Taking what you read in the docs and then using it to solve the issue you are solving is not always easy. I was just running into that with Elasticsearh this week. Sometimes it takes asking a question and getting some clarification for the pieces to snap together.

I go to where the search engine points me to.

Sometimes medium is better because it has examples. I want the direct answer to my problem, the one liner. I don’t have time to read a book/doc.

Reply on news.ycombinator.com