I just wish many of the docs were better.

I see this 'style' many times in some docs. A bit of doc that basically describes the name of the function/class. But does not show why and how to use it, how it fits in the API system, and so on.

public void DoesXYZ()

Then many times a description of 'a public method that does XYZ' does not return anything.

It is exceedingly unhelpful but meets the 'it is documented' checkmark.

My next step would be to search for an example usage of that thing (usually landing on something like SO or some random training site). Then what sorts of items might it need to work. Why would I use it over something else? Some OK examples of what is going on goes a long way and what sets the expectation of the original dev on how they were expecting you to use it. So I end up spending some decent amount of time reading the tea leaves and if I am lucky the code itself to decode what is going on.

One feed back I consistently give to all vendors is 'your docs need examples and those examples need to be consistent with each other' If I have to open github and spend a few hours reverse engineering that code, and then also try to learn whatever language you thought was fun to play with 6 years ago, I am not going to be happy.

Exactly. Examples always trumps some convoluted explanation.

Good docs are like: "this library make you do things like this, this or this, as easy as [show code snippet 1, 2, 3]".

Also a big list of examples should be way easier to just dump into the docs than writing some absurdist essay about the tech, ie. it's even easier for the maintainers.

I vaguely remember the PHP website doing this with their functions on their website with user comments with examples - another example is Mozillas MDN.

Honestly now thinking about it, "user added examples" should be its own category on sites like Github. Seriously why isn't this a thing?

Dozens of "Here's how i used this library to do this" would be amazing.

That's just lazy javadoc style. The worst kind of documentation, since it adds nothing over looking at code itself.

At the very least, there should be examples of usage.

I never did PHP, but they have one of the best documentation features: comments. It allows you to recognize if a function is a footgun: https://www.php.net/manual/en/function.utf8-decode.php

There is a difference between documentation and tutorials.

Very much so. But many times just a small example putting the thing in context of usage helps a lot. Sometimes that is needed sometimes it is not. This style is especially useful if you have a call/anticall style like malloc and free. An example of malloc could also have an example of free along with it indicating to the reader (hey you want this too). Some docs it is not obvious what the matching call is.

That's always been my special skill, and it's not even just programming.

Back in school I was considered a "leet hacker" who was good at computers. I "cracked" an encrypted Word document when someone forgot the password to it (I Googled how to do it). I built my own PC (I Googled how to do it). I downloaded MP3s before they were everywhere (I Googled how to do it). You get the idea...

Nowadays I get paid to do that stuff, but at home I fix my own car when I can, fix my plumbing when I can, fix and maintain my bicycles, do my own networking etc. How? You guessed it... I DuckDuckGo how to do it.

This is precisely what I have realised is my special skill as well!

I can read the manual / docs and I can cast an eye over third party packages to see how it works it astounds me that so few people take these simple steps.

This is why I laugh when people denigrate modern software development as “just glueing libraries together.”

Lol, as if that’s an easy or trivial thing…

A big portion of learning embedded development is learning to read data sheets.

Same. I'm often surprised as to how far programmers will go to disparage the quality of docs, as opposed to just reading them. Like I get that there are factors affecting their accessibility, e.g. internationalization, but it is your literal job to read this information.

Meanwhile, for reverse engineers, it's a dream come true to be granted any information whatsoever on the product they're reverse engineering. For some reason, programmers want to operate in the context?

I interview people based on their ability to cheat on the assessment, as finding the answer and adapting it efficiently more closely matches the day to day job.

The person that figures out how to copy and paste code for a REST call in that particular framework will still probably fail if they don't notice that they need to adapt it for the network request caching system and the ORM.

But there is no reason to memorize all that syntax and regurgitate it in the most computationally efficient Big O

I think we may be thinking about this differently.

I value reading the documentation of libraries that I'm using. I don't memorize it, but casually read over it to understand what's possible.

I do not do this for everything, but if it's a piece of technology that I value, then it's probably a good idea to read the docs so that I'm not faced with "I did not know that it could do that" situation.

The amount of times I've seen developers painfully code around something that was already supported in the library they're using is suprizing.

how fast though ? I've read emacs manual. over 20 years :) (and in 3-4 passes)

I _do not read_ the docs. I read the readme in githib, if there is not enough information in it for my use case, I may continue searching.

Also, when I find a lib, I want to read some user stories, not 20 pages of documentation in yet another doc format. Simple user stories. If you need to do A, here are 3 lines. If you need to do B - here are 5 lines. If your lib lacks these user stories, I will probably skip it. Or if I really need it, I will use StackOverflow to find some use cases so I can relate to and get a better understanding of the lib.

_NOW_ I may read the docs after I have the user stories, so they better have some information how you can customize the 3 and 5 lines of code above.

I think you're getting downvoted because none of what you mentioned isn't docs. You do read them, you just read a specific type of documentation.