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.