Re: best git practices, was Re: Git User's Survey 2007 unfinishedsummary continued

["J. Bruce Fields" <bfields@fieldses.org>]

On Thu, Oct 25, 2007 at 01:06:02PM -0500, Federico Mena Quintero wrote:
> On Thu, 2007-10-25 at 12:38 -0400, J. Bruce Fields wrote:
> 
> > It's definitely not a simple cut-and-paste--even with permission from
> > the author of "Git for computer scientists", fitting this in would
> > require rethinking the ordering of topics in the manual.
> 
> Oh, that can be done.  It's easier to move text around than to
> rearchitect code :)

OK!  I'm happy to help review patches, etc.

> > Also, there's
> > the restriction that we'd like to keep it looking good in plain ascii,
> > so diagrams have to be done in ascii somehow.
> 
> Hmm, what's the rationale for this?

There have always been a lot of complaints about the difficulty of
building the documentation.  (I don't know why; at least on Debian all
you need is an "apt-get build-dep git-core".)  And our response has been
"no problem, you can just read the source."  That's a big reason why
asciidoc was chosen.

> I'd assume that most people read the user's manual as a web page (or
> as bedside reading if they can print a PDF thereof), where diagrams
> can be pretty.

Yeah.  Heck, I just read it by pointing my web browser at kernel.org's
html copy....

So you might get some sympathy for a request for fancier diagrams, I
don't know.  It would require some more discussion, so I'd rather not
have other improvements blocked by this.

--b.