Earlier quoted context omitted.
> This is a good point. I think once developers learn Git (or as much as they need to use), then they forget how esoteric the the cli tool is. This is more up to git being horribly leaky about all it's internal implementation details. I'm not a git developer, and not even that great a user, but I know about trees and indices and refs and refspecs and packs and reachability and objects and merge drivers and smudge and…
I think that's a bit unfair. It presumes git is trying to abstract it's internals in the first place. It's not. Git is unapologetically a tool for manipulating a DAG, and puts that right in your face. This has pros and cons. The obvious con is that it has an immensely steep learning curve and, for users who cannot develop a mental model for how it works, forces people to rely on cargo culting. The flipside is that it…
So you actually agree. To understand the docs you have to understand git jargon, and the docs aren't too helpful about that.
I certainly don't want to say that the git docs are bad. They're quite complete and written in mostly complete sentences, which is already pretty good as far as documentation goes. Doesn't mean that there is a lot of room for improvement.