Hi,

On Sat, Jul 26, 2008 at 12:07:03AM -0700, Scott Chacon wrote:

On Fri, Jul 25, 2008 at 6:53 PM, Petr Baudis [off-list ref] wrote:

quoted

 Plenty of minor fixes are available for pull at

       git://github.com/pasky/learn-github.git
       (http://github.com/pasky/learn-github/tree/master)

I've pulled in all this stuff and it should be live now.

  thanks.

quoted

 Other non-trivial nits:

 * I'm feeling a bit uneasy about listing so many projects using Git;
I haven't heard about quite a few of these and I'm not sure on what
merit should we list projects. "Prototype" or "Liftweb" and probably
even "Rubinius", is that going to ring a bell for major part of visitors
so that they say "oh, even _those_ guys are using Git"?

Based on a conversation in the other thread, I think we should have a
list that is suggested by the community and just have the 3 or 4 that
are really famous (Git, Linux, RoR...) and have the rest randomly
pulled from that list - changed every day or so.

  Maybe it is because of my general background, but I think X.org, WINE
and Fedora (probably in this order) really belong to the list as well.
If you say Prototype and MooTools are huge projects that are very
well-known in the web programmer community too, it makes sense to
include them as well; and that would be it. I might add

	<p align="right"><em>...and many more</em><p>

below the list.

  Having some of the list randomly generated is an interesting idea, but
it should be clearly visually separated from the static part, and it
would probably take a bit of work to tune this to show only interesting
projects ($size * sqrt(activity)$ or something).

quoted

 * Reusing captions from command manpages in the Documentation page
shows nicely how awful they sometimes are. :-) This is probably something
to fix upstream, though.

I saw you changed some of these, I can take another pass.  I'm not
entirely sure how useful it is to have the commands on that page, to
tell the truth.  This may go away as the documentation page evolves.

  I agree. I changed none though, I just reordered some of the commands.

quoted

 * Is "Git for the lazy" really unique in some regard to deserve to be
listed among the other resources? I think we should minimalize
redundancy at the documentation page, the amount of material is already
overwhelming and it should be obvious for the visitor which document to
choose based on his needs. I have similar doubts about the 37signals
resources.

       In other words, "let's keep the resources orthogonal!"

I agree - I would like to pull a lot of the information in those links
into one open-source book that is kept up by the community and hosted
at this page.  The documentation page will change significantly as we
try to simplify and maximize the usefulness of the page.

  But that's a long-term project, I'm talking about the usefulness of
some of the links right now.

quoted

 * There is no reference to the Wiki in the documentation, only to the
[GitDocumentation] page; I think there should be a reference to the
[GitFaq] page too - a lot of important points that are not obvious
to newcomers are covered there. I'm just not sure where exactly to put
the link.

 * I would go as far as put the link to the Wiki itself to the
navigation bar, simply since it is such a crucial resource.

Perhaps I should just do this - would that cover the previous one as well?

  It seems you did, which is great! I think there should be a direct FAQ
link as well, though.

quoted

 How does that compare with the Git user manual? Have you considered
collaborating on that one, or what are your reasons not to? Or are you
trying to do something different?

I would like to - I have personally found that invaluable in learning
Git, but I would like it to be more digestible and I would like to add
a lot of supporting media to it - screencasts and diagrams, to help
people that are more visual learners. Loading up a document where the
TOC is several pages long is intimidating and difficult to start and
stop with.

  Making it more digestible is certainly a worthy goal. :-) I think both
screencasts and diagrams could be valuable for the user manual, but
the question is how to best integrate them into the manual and if it
makes sense to do this within the Git tree, or how to cross-merge.
However, at the documentation side I focus pretty much exclusively on
improving the reference documentation, so that's not for me to discuss.

-- 
				Petr "Pasky" Baudis
As in certain cults it is possible to kill a process if you know
its true name.  -- Ken Thompson and Dennis M. Ritchie