
Ask HN: Why doesn't anyone ever read the docs? - snejad123
This is one of the strangest behaviors i&#x27;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.).<p>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&#x27;re one of the types that prefers medium&#x2F;YT over the documentation) prefer these off-hand interpretations of a program rather than the one who created it ?
======
bjourne
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-...](https://alvinalexander.com/photos/linux-ls-command-how-sort-by-
filesize-reversed) 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.

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

~~~
bjourne
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

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

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

