Fun. Unfortunately, I think it's a bad sign when random mambo-jumbo generated by a Markov chain script looks so much like the real stuff...

Markov chains help a lot in making the output look like the real stuff, that's kinda their purpose in this case. Heck, there have been automatically-generated conference papers that have been accepted and went through peer review (although this might tell a lot about that process, too ...).

git manpages are apparently full of very git-specific terminology and quite dense. I would guess the same model applied to the J documentation would be equally unreadable for the uninitiated. If the source material was more readable and easier to grasp the automatically-generated versions would reflect that (to some degree, until it's obvious that's nonsense).

The generator doesn't use markov chains, it's grammar-based similar to the Dada Engine which powers the postmodernism generator. There's a link to a markov chain based generator in the footer, check it out, it's pretty funny and a lot more random.

I stand corrected on that point, then. But still, I guess it's no surprise that something tailored to look/sound like something else looks/sounds like that something else ;-)

> Heck, there have been automatically-generated conference papers that have been accepted and went through peer review

Those papers were used to prove that those conferences weren t actually peer reviewed.

I wonder, since this is an obvious parody of the sorry state of git's manpages, do people find Mercurial's manpages any easier to read?

http://www.selenic.com/mercurial/hg.1.html

Mercurial's seem to assume less knowledge, the bisect pages are a good example.

Mercurial bisect:

    This command helps to find changesets which introduce problems.

Git bisect:

    Find by binary search the change that introduced a bug

Someone could happily use Mercurial bisect without knowing that it is doing a binary search. The Mercurial docs also get into simple examples before explaining all the options, while the git docs list all of the options first, which presumably could scare people away who are just after simple usage.

On the flip side the git docs provide more useful information about what it's actually going to do to help you, not just in general how it'll help you.

actually, I don't care if git uses binary search or any other algorithm. I care that it helps me find bugs fast. There could be a "if you're interested in the tech" part in the git manpages that adds the information for the people that want or have to know, but I, as a user, couldn't care less - I can't change it anyways.

To make the obligatory car analogy:

    git-car uses a synchronized system of pistons 
    and electrical arcs to extract energy from 
    hydrocarbon chains and convert it linear motion

Which is (a) what a car does, and (b) not how it's described in the car's manual.

Well, sort of. What happens when you run out of fuel (hydrocarbon or electric)? You have to know that it's a hydrocarbon-based engine, more so you need to know it's a spark-based engine (gasoline), not a pressure based engine (diesel), or even something else (CNG).

Also, if I want to get the most performance out of the car, or do something nonstandard, I need to know about the energy extraction process in order to pick better fuel or to adjust timings in the engine. (Sure most people won't, but if you want to, it's nice to have the information available).

True, but cars deal with this by having separate manuals for normal owners and for maintenance. Owners usually need information like how often to change the oil and what pressure the tires should be at, but they're less likely to need engine timings.

Git's documentation (from what I hear, anyway, I've barely used it outside the GitHub client) seems like it's written to say "Everyone using git is a programmer, so everyone using git wants to know about git's implementation details."

As someone who would rather have a handle on the basics (and 99% of use cases) before digging into that, google does a better job at explaining what things are for. Which works, but I really wouldn't mind having some canonical user-friendly documentation available instantly on my computer.

No, I don't need to know the exact details of the engine. Your cars manual probably does not list the exact engine timings either. It says "fill in diesel here." If I want to tune my car I read the workshop manual, not the user manual. I totally support that the workshop manual exists, but git is lacking a users manual. I can explain my tester to run automatic tests, I can teach them git, but if I point any of them at the gut manual, I get a blank stars. It technobabble to them.

What matters is that 'git bisect' helps you find the bug in a significantly smaller number of steps than trying all revisions by hand. The manpage should definitely either mention the algorithm (binary search), or the reason why you would use it in the first place (it significantly reduces the number of steps until you find a bug, versus trying all commits). Note that the 'hg bisect' still fits this requirement, because its name hints at the algorithm.

If it only mentioned that it finds the changeset introducing a bug, without saying how, or that it does it efficiently what would be the reason to use the command at all?

Well, why not say "finds the rev in which a bug was introduces in an efficient way." Why bother me with further details? I don't care how - if the git team finds a better way to do it, fine.

A lot of potential git users won't be aware that binary search is what you want. You just lost those.

Given that HG still calls it "bisect" rather than "find-changed" or something, I would be surprised if it didn't use binary search.

The point is that you don't need to know.

and yet I still switched to Git, knowing all this, and don't regret it, because it gives me enough power to fit my workflows rather than me serving my VCS all day.

There are now a large number of friendly ways to learn git, if you don't like the man pages then don't use them. It's not exactly uncommon for man pages to have technical material in them

I find it really accurate to my experience with Git man pages, e.g: https://www.kernel.org/pub/software/scm/git/docs/

I did not think a random-thing-generator could possibly make me laugh again, but for me `git-shoot-subtree` was the undeniable breaking point.

I made a (very childish) bookmarklet to make it more fun :)

http://people.cs.umass.edu/~jvilk/bookmarklet.html (The "javascript:" link for the bookmarklet is on this page)

Click it when you're on a Git manpage, either legitimate or generated.

I wish it had permalinks.

That's a great idea. I'll see what I can do!

Edit: Just added the permalink feature, thanks for the tip!