Go is the same. Everyone, including the stdlib maintainers seem to think a few lines of comments per method is the same as documentation on how to use the package, best practices, pitfalls, etc.
This is the part that blew my mind. For simple functions ("how do I read from a buffer again?"), the code example is more useful than any number of paragraphs of description, especially because its correctness is enforced by the compiler. Switching to learning Node after Rust has been a major step backwards and involves a lot more time on Stack Overflow.
(Unrelated gripe: if I could ban w3schools from my search results, that would be great.)
If you can’t tell a story with text, you won’t be able to tell it with code either. The thing that makes people want better documentation is the same thing that makes it difficult to get.
I remember years ago using Ant as a build tool and the only way I figured it out was to Googlestalk the author. Given enough answers to questions in enough places I finally developed a theory of the system. It was still supremely weird to convince it to do certain things but at least I was able to.
You’re not telling a story to a computer. You’re telling it to your coworkers. The people’s code that’s most frustrating to work with share your philosophy. They are often so convinced they’re right that they can’t even hear constructive criticism. That’s not my opinion, that’s the consensus view shared over lunches and coffees with their coworkers, across many jobs.
