Hacker News Reader

Comment by ajross | Hacker News Reader

I loved this article. That being said:

This brings us to another of git’s faults: its documentation is terrible. Man pages are no longer a sufficient replacement for a good, well-updated wiki or reference work;

Huh? This is the kind of thing that IT pedants say when they don't have any better arguments. There's absolutely nothing wrong with a good man page (or, to be sure, any documentation format at all). /usr/bin/man, in 2008, is still my first choice for looking up the interface to system calls, C APIs and command line utilities like git.

Now, could some of git's man pages use some work? Sure. But make that the criticism. Smacking about the format is just dumb.

View on HN

...What if there was a wiki that people could use to participate in the documentation, and then that documentation would become the man page with the next release? Everyone wins?

I like and use both man pages and wikis, but I'm not sure how I would even begin to participate in helping with documentation for something like a man page if I wanted to. The actual creation of the man page itself, as I understand it, is a single-user task. If you want community involvement to get source material, you're going to have to have an accessible participatory mechanism; a wiki, essentially, in whatever form that may take. But it should be easy, no?

I suppose there's also the counter argument that "people who need wikis to participate in something like git documentation are probably not the people we want writing git documentation."

http://book.git-scm.com/

Boom! That's a great site. Thanks for sharing.

Well put. I'm appalled that people keep promulgating this FUD about git documentation. Git's User Manual (http://www.kernel.org/pub/software/scm/git/docs/user-manual....) is the first hit on Google for "git manual". From my reading, it's roughly equivalent to the much-lauded Mercurial book.

The author then writes: "I installed git through MacPorts, only the main git tool comes with a man page, leaving me to consult the Web to find out exactly how to format revision specifiers." He did not seem to realize that the git-core port has a nifty variant "+doc", which installs full documentation, including the aforementioned manual.

Like the constitution.. it is written on parchment! Parchment! How terrible. You can't search it or handle it with your bare hands.

That being said, it is easier to update a wiki than to get a man page updated. This may foster better or more documentation, but ultimately the format does not dictate the utility.

Reply on news.ycombinator.com