Why doesn't anyone ever read the docs?

Question

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 ?

bjourne · Accepted Answer

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.

chupa-chups · Answer

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.

jppope · Answer

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

blacksqr · Answer

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.

markus_zhang · Answer

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.

jerrac · Answer

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.

billconan · Answer

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&rsquo;t have time to read a book/doc.