Hacker News new | past | comments | ask | show | jobs | submit login

Is the documentation really that bad? Would it benefit from a technical writer going over it? Is the project open for discussion on changes to the documentation?



Git is like Perl. And not in any of the good ways.

Perl 5 -- I don't know enough about 6 to know whether this is still the case -- involved a couple of design decisions which worked well for one subset of people and did whatever the complete polar opposite of "works" is for a different subset of people.

One of those design decisions is the famous "there's more than one way to do it". Ask five Perl programmers to solve a simple problem in the language and you'll get fourteen solutions, and no way of knowing which, if any, is to be preferred in real-world use. Git similarly tends to have multiple ways of achieving a given goal, and endless words have been devoted to documenting them; nobody has yet settled which of them is or should be generally recommended, or if there even can be such things as generally-recommended ways to use git.

Perl also involves an incredible amount of memorization. The large collection of "magic" variables which can be read or set to determine language and local-scope behavior are daunting and can't be mastered through any process other than rote memorization. And the differing behavior of basic operations depending on context produces a combinatorial explosion of possibilities which, again, are not amenable to any technique short of rote memorization. The same is true in git: though there are underlying abstractions, the interface provided to them is inconsistent, varies depending on sometimes-invisible contextual factors, and ends up requiring rote memorization of commands and options and how they behave in any given situation.

Unfortunately, no amount of documentation or review by technical writers can fix this. A bad API can't be made good through better documentation, it can only be made good through being replaced with a better API.


I am a long-time Perl user and also a long-time Git user.

Git is worse than Perl. Perl is just opinionated: despite what you are saying about it is true, you can write working programs and have fun at all levels of Perl mastery. There's a lot to memorize, but you can start coding immediately and do something useful. Also, Perl community is incredibly friendly and helpful.

Not so with Git. If you start without thorough understanding how Git internals work, you will get burned really soon. And more often than not, the only response you'll get is the arrogant RTFM or the link to Pro Git book.


Good points. Also, git (not Perl though) was designed by a genius for himself (and a few other geniuses). All of whom don't know how much of a genius they are / don't comprehend how comparatively dumb the rest of us are. So, the git ui assumes you either "wrote git" or "have read the source and are smart enough to understand all it's implications".




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: