Some documentation is sadly lacking generally, but even some very good documentation in terms of detail is not terribly useful to a beginner as it is often more a reference work for people with some experience.

With a bit of experience a detailed reference is great, but it can completely overwhelm a beginner who is better served by being given some simple worked examples of a core sub-set of features/methods/properties/processes/… then being given the more referencey docs to find the other details (ideally with some starting pointers, linking what they were shown in the tutorial examples to relevant bits of documentation).

Remember when 4X games came with paper reference manuals? If you skip the SMAC tutorial and go through the reference in order you'll hit the copter and hovertank units (late-game additions that you don't need to care about initially) long before the speeder (something you have access to early on, from the start in the case of one player faction). Just giving beginners reference docs is much the same thing.

Many have become attuned to searching for a tutorial elsewhere, assuming the docs will be overwhelming initially, even if more introductory information is available for a given thing. Also, many or introduced to new libraries and such through tech blogs, another reason for that being their starting point. And of course if searching via Google et. al. you have the issue of blog-spam that is SEOed to the nth degree coming up before the better documentation.

>>I'm also confused... who reads blogs but doesn't read the docs?

Most docs are hard to read- dense text, millions of options, and not a single example of a use case. Same with most man pages.

90% of the time, I just want to do something simple, and its easier to read thru blogs than trudge thru a dense hard to read official document.

And with Python-- you are guranteed to get out of date docs in Google search. Not just for Python 2, but older unsupported versions of libraries

Sometimes, the page even helpfully tells you it is out of date, and invites you to go to the home page and start searching again (rather than, you know, just link to the latest page)

> I'm also confused... who reads blogs but doesn't read the docs?

I’d say lots of people. Most people are searching for a specific solution to a technical problem. If they see a how-to blog that fits their use case in the results, many people will prefer it over the official docs.

This is particularly true because docs explain functionality and rarely mention use-cases.

That's honestly entirely dependent on the doc base. Case in point : learning C# recently I've done everything I could to escape Microsoft's official doc and found myself on a lot of blog posts expounding on topical issues I was encountering. It both makes an incredible amount of assumptions and goes for the most cryptic syntax at all times.

> I'm also confused... who reads blogs but doesn't read the docs?

You've been spoiled by good docs ;).

More like I haven't been spoiled by good blogs. ;-)

Docs are often very terse and assume a lot of background knowledge. When blog posts are written effort is put in to make sure a wider range of audiences can understand them.

Why does this make you sad?

Because, to me, reading the docs & source code should be skills that are learned prior to "using the code and writing code".