> I always have the feeling people just cobble around for too long and should instead take at least a few days for a more structured learning approach.
There are two kinds of documentation: there's a list of all the individual things you can do, and there's a "The fundamental abstraction is this". The second is rare, and rarely done correctly, and much more important.
A lot of people assume that X is like Y, but with Z, and they know Y, so they just need to learn about Z. A lot of time that isn't true, the fundamentals are different. The natural way do perform W in Y might be profoundly wrong in X. Examples:
* git is like subversion, but distributed.
* C++ is like C, but with classes.
* C++ is like Java, but you have to remember to delete stuff.
I love git. I love C++. I think these things are the bee's knees. They're so simple and elegant. But I totally understand how people think they're arcane eldritch horrors when you're holding the sword by the pointy end.
In most cases, I'd settle for "what problem this is trying to solve" (although this is obvious for CSS, it isn't nearly as obvious for things like React and Vue).
Can’t agree more. The first kind of doc is useful from time to time to check the correct argument of a function. The second one is about the big picture and the overall architecture. And sadly this is what is missing with every codebase I’ve worked on. In my project on the contrary, this is something I try to document.
If someone needs to read documentation for a few days in order to figure out which end of the sword to hold, perhaps the sword was just poorly designed and unintuitive.
So you want a dull sword with handles on both ends just so that nobody can possibly cut themselves? Professional tools are meant to be efficient for those trained in using them and if that means they are slightly harder to learn that's OK.
There are two kinds of documentation: there's a list of all the individual things you can do, and there's a "The fundamental abstraction is this". The second is rare, and rarely done correctly, and much more important.
A lot of people assume that X is like Y, but with Z, and they know Y, so they just need to learn about Z. A lot of time that isn't true, the fundamentals are different. The natural way do perform W in Y might be profoundly wrong in X. Examples:
* git is like subversion, but distributed.
* C++ is like C, but with classes.
* C++ is like Java, but you have to remember to delete stuff.
I love git. I love C++. I think these things are the bee's knees. They're so simple and elegant. But I totally understand how people think they're arcane eldritch horrors when you're holding the sword by the pointy end.