On Mon, Mar 9, 2015 at 5:52 AM, Waldman, Simon M <[email protected]> wrote: >> In their defense, the Git docs are open source and written mostly by >> volunteers (like our lessons). I'm sure they'd appreciate patches clearing >> up >> anything that strikes you as confusing, but balancing clarity, correctness, >> completeness, and backwards compatibility can be hard. > > I don't think the git docs are inherently any worse than most man pages or > other open source documentation. None of these things are easy to understand > for somebody who is not of the "concise, accurate and literal" computer > science mindset, IMHO. > What perhaps makes the git docs worse is that (a) They require familiarity > with git concepts that the beginning reader many not have, and that (b) git > syntax itself is confusing and inconsistent, as summarised nicely by the Git > Koans that somebody linked :-)
Agreed--like most docs I'm sure there are areas for improvement. But it's not like I think they're *bad*. When I know what I'm looking for in them they're pretty useful. Some of them even contain nice "discussion" sections that contain useful tips. And anything where I need more hand-holding I think is covered pretty well by http://git-scm.com/book/en/v2 Understanding them in full though just requires an awful lot of prior knowledge. That's true for most man pages and that's okay (I think). They just tend to be *particularly* heavy on strange-seeming jargon and lengthy exposition compared to something like, say, `man ls` (which has a million options many of which also involve strange jargon, but is otherwise pretty terse). Erik _______________________________________________ Discuss mailing list [email protected] http://lists.software-carpentry.org/mailman/listinfo/discuss_lists.software-carpentry.org
